github-community-projects / github-community-projects/safe-settings
Generated schemas keep OpenAPI `nullable`, so required-but-nullable fields reject null
- Dominant language
- JavaScript
- Stars
- 921
- Forks
- 226
- Avg merge
- 18h 3m
- Merged PRs (30d)
- 14
Description
The schemas in `schema/dereferenced/` declare `"$schema": "https://json-schema.org/draft/2020-12/schema"`, but `script/build-schema` copies subschemas out of GitHub's OpenAPI **3.0** description, which marks null-able fields with `nullable: true`. That keyword doesn't exist in JSON Schema draft 2020-12, so any compliant validator ignores it and the fields reject `null`.
This bites exactly where the GitHub API forces null into configs. The update-branch-protection endpoint requires `required_status_checks`, `enforce_admins`, and `restrictions` to be present, and documents "Set to `null` to disable". A minimal config:
```yaml
branches:
- name: main
protection:
required_status_checks: null
enforce_admins: true
restrictions: null
```
fails validation against the current `schema/dereferenced/settings.json`:
```
$.branches[0].protection.required_status_checks: None is not of type 'object'
$.branches[0].protection.restrictions: None is not of type 'object'
```
There are 13-14 `nullable: true` occurrences per generated file, all silently dropped this way.
GitHub publishes an OpenAPI **3.1** variant of the same spec (`descriptions-next/`, same dated snapshots). 3.1 is natively JSON Schema 2020-12: those fields are `type: [X, "null"]` unions and `nullable` doesn't exist. Pointing the build at it makes the generated schemas actually conform to the dialect they declare, with no post-processing.
Contributor guide
Research direction
Start with script/build-schema and inspect how it selects the GitHub OpenAPI snapshot, then compare that source with descriptions-next/. Regenerate schema/dereferenced/settings.json and validate the nullable configuration shown in the issue; done means required_status_checks and restrictions accept null under draft 2020-12 without relying on nullable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github, javascript, openapi
- Domain
- api, build-system, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100