[Schema Inaccuracy] Webhook field definitions are missing "type"

[ksitze]

Schema Inaccuracy

As part of digging through the Webhooks schemas I'm finding several dozen errors where schema types are missing.

Here are a few examples:

jq ."gpg-key".properties.subkeys.items.properties.subkeys.items < schemas.json
{}

jq ."webhook-code-scanning-alert-created".properties.alert.properties.dismissed_at
{
  "description": "The time that the alert was dismissed in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`.",
  "nullable": true
}

jq ."webhook-code-scanning-alert-created".properties.alert.properties.dismissed_by
{
  "nullable": true
}

jq ."webhook-code-scanning-alert-created".properties.alert.properties.dismissed_reason
{
  "description": "The reason for dismissing or closing the alert. Can be one of: `false positive`, `won't fix`, and `used in tests`.",
  "nullable": true
}

jq ."webhook-code-scanning-alert-created".properties.alert.properties.fixed_at
{
  "nullable": true
}

Expected

The attached jq.paths.log file contains all entities detected to be missing a type field. The paths are all relative to the .components.schema definitions in the 11MB OpenAPI file api.github.com.json as found in the GitHub repository github/rest-api-description.

Reproduction Steps

Download the attached file:

jq.paths.log

Download GitHub's JSON formatted OpenAPI definition file.

% curl --output api.github.com.json \
     https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json

Extract out the schema section:

% jq '.components.schemas' < api.github.com.json > schemas.json

The relevant JSON paths in jq.paths.log can be explored.

while read line
do
    printf "\njq '%s'\n" "${line}"
    jq "${line}" schemas.json
done < jq.paths.log

Each of the indicated JSON paths reference a schema element missing a type declaration. Most are likely "type": "string" (with a corresponding format (e.g., date-time)) but it is not obvious in certain cases what the correct values are.

[tiabas]

@ksitze is this limited to just webhook-code-scanning-alert-created or is it for all schemas under webhooks? Our, current thoughts are we can have the teams that own each event-schema update it themselves but first, it would be great to know how many unique schemas are affected.

[ksitze]

It is for all schemas including the REST schemas. I’m only finding problems mostly under the Webhooks section as per the attached file. It also appears that some of these may have been deliberately left unspecified for OpenAPI to allow for any type.

Nevertheless, it is clear that many are simply wrong. Date members listed are, for example, specified as nullable but have no type or format values, despite seeing other members with the same or similar name having explicit types and formats.

The paths in the attachment are as complete as I could make them. I wrote a program to crawl the entire OpenAPI schema set looking for problems, which is what generated the file I attached here.

I’m assuming that every type-less definition is an oversight as the other schema definitions are quite clean; not having seen anything generated for 99% of the REST API schemas. I have ideas about why this might be but as there are still one or two non-webhook issues I can only make guesses as to the disparity.