github-community-projects / github-community-projects/safe-settings

Generated schemas keep OpenAPI `nullable`, so required-but-nullable fields reject null

Open
#1,024 0 comments 0 reactions 0 assignees View on GitHub
bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.