Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
ksitze opened this issue Feb 23, 2024 · 2 comments
Open

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

ksitze opened this issue Feb 23, 2024 · 2 comments
Labels
documentation inaccuracy rest-schema

Comments

@ksitze
Copy link

ksitze commented Feb 23, 2024

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
Copy link

tiabas commented Feb 26, 2024 •
edited
Loading

@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
Copy link
Author

ksitze commented Feb 26, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
documentation inaccuracy rest-schema
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@tiabas @shiftkey @ksitze