[Schema Inaccuracy] inconsistent issue schemas in webhooks

Open
#6,448 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Quiet
Tech stack
openapi
Domain
api

Research direction

Start in descriptions/api.github.com/api.github.com.json and compare the issue fields in webhook-issues-milestoned, webhook-issues-unlocked, webhook-issues-untyped, and webhook-issues-unpinned. Read the related issue #4622 for context, then determine whether the referenced and inline schemas are interchangeable. Done means the issue webhook schemas have a clearly consistent issue definition, or documented differences where they are not interchangeable.

Written by the indexing model from the issue text.

Description

feature

Schema Inaccuracy

In the webhooks schema for issues, there are several different definitions for issue objects; #/components/schemas/webhooks_issue and #/components/schemas/webhooks_issue_2 are used on several webhook types related to issues. Furthermore, most of the issue webhooks define the issue object inline.

(I think that issue #4622 describes a similar problem.)

Expected

Why are there different types for an issue object? It's hard to tell from exploring the raw json of the types whether the issue object attached to each type of issue webhook is the same, or if there are important differences in the fields included. I'm writing code that processes webhooks, and if all issue webhooks had one consistent type for issues, the processing logic would be much simpler.

(Also, this problem is not limited to issues. Pull requests seem to also be inconsistently defined.)

Reproduction Steps

In the descriptions/api.github.com/api.github.com.json file, compare the following types:

  • webhook-issues-milestoned
    • contains an issue defined inline
  • webhook-issues-unlocked
    • contains an issue defined inline
  • webhook-issues-untyped
    • contains an issue of type #/components/schemas/webhooks_issue
  • webhook-issues-unpinned
    • contains an issue of type #/components/schemas/webhooks_issue_2

Are these types interchangeable? Again, it's very hard to tell, as these are huge json blobs. Are the inline definitions of issues (in the milestoned and unlocked webhooks) the same?

Dominant language
No language data
Stars
1.6k
Forks
342
Avg merge
3h 33m
Merged PRs (30d)
51

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/rest-api-description

All issues in github/rest-api-description

Similar issues

More Backend & API Design issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.