[Schema Inaccuracy] Clarify use of default values defined in the schema

[netomi]

Schema Inaccuracy

Certain operations, e.g. Update organization define default values for some of their optional body parameters.

According to the openapi specification, a default value is the one that the server uses if the client does not supply the parameter value in the request . In my tests I can not confirm that the server conforms to that.

Expected

I would expect that the rest endpoint honors the default value as specified in the api documentation. In my tests the behavior is quite inconsistent. Usually the default values are not taken into account when an optional values is not specified. I noticed a few corner cases where the server seems to take a default into account when it actually should not (seems like a bug):

have web_commit_signoff_required = true and members_can_create_private_repositories = false
setting web_commit_signoff_required to false will automatically trigger setting members_can_create_private_repositories to true

Reproduction Steps

Making a rest call to update an organization setting a value with a default, e.g.

set members_can_create_public_pages to false which according to the rest spec should have a default of true

curl -X PATCH -H "Accept: application/vnd.github+json" -H "Authorization: Bearer " -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/orgs/OtterdogTest -d "{"members_can_create_public_pages": false}"

set members_can_create_pages to false, which should trigger members_can_create_public_pages to be enabled again

curl -X PATCH -H "Accept: application/vnd.github+json" -H "Authorization: Bearer " -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/orgs/OtterdogTest -d "{"members_can_create_pages": false}"

the result is that both settings are false, no default value seems to be taken into account.

Discussion

In general I find default values for updates to be dangerous, as it forces you to specify all values all the time when updating a specific field. There are some tools (like https://github.com/yanyongyu/githubkit) out there that parse the published schema and honor the api spec, i.e. set default values where specified in the spec. I find this behavior quite surprising and unexpected, sos I would like to have clarification on the purpose of the default value in the rest spec if it matches the intention of the openapi baseline or serves another purpose.