[Schema Inaccuracy] pull-request-review.state and two siblings should be enum, not string

Open Beginner friendly
#6,345 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
70/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Quiet
Tech stack
openapi
Domain
api

Research direction

Start by locating the component schemas pull-request-review.state, timeline-reviewed-event.state, and webhooks_review.state, then compare them with the documented API values and the inline webhook-pull-request-review-dismissed.review.state precedent. Done means the REST schema lists the five uppercase values, while the timeline and shared webhook schemas list the four lowercase submitted-review values.

Written by the indexing model from the issue text.

Description

documentation

Schema Inaccuracy

Three schemas type their review state property as a plain string rather than an enum, even though the value is constrained to a documented set.

REST (uppercase values):

  1. components/schemas/pull-request-review.state{ "type": "string", "example": "CHANGES_REQUESTED" }. Used by GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews and every other endpoint returning a review.

Event records (lowercase values):

  1. components/schemas/timeline-reviewed-event.state{ "type": "string", "example": "CHANGES_REQUESTED" }. Returned by GET /repos/{owner}/{repo}/issues/{issue_number}/timeline. The example value here is uppercase, but the live API returns lowercase for this surface (see Reproduction below).
  2. components/schemas/webhooks_review.state{ "type": "string" }, $ref'd from webhook-pull-request-review-submitted.review and -edited.review. Webhook payloads deliver lowercase.

The canonical value list is GitHub's own GraphQL PullRequestReviewState enum: APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED, PENDING. Prior precedent for citing the GraphQL enum as the source of truth: #74 (author_association), which was resolved by introducing a shared author-association component schema with the enum drawn from the GraphQL CommentAuthorAssociation enum.

Expected

pull-request-review.state (REST) should enumerate the uppercase values the API returns:

"state": {
  "type": "string",
  "enum": ["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED", "PENDING"],
  "example": "CHANGES_REQUESTED"
}

timeline-reviewed-event.state and webhooks_review.state should enumerate the lowercase values these surfaces actually deliver (pending is omitted because reviews don't reach event records or webhook payloads until submitted):

"state": {
  "type": "string",
  "enum": ["approved", "changes_requested", "commented", "dismissed"]
}

The inline webhook-pull-request-review-dismissed.review.state already declares the enum ["dismissed", "approved", "changes_requested"] directly — precedent for the same fix on webhooks_review.state.

Reproduction Steps

REST pull-request-review.state returns uppercase:

$ curl -s -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2022-11-28" \
    https://api.github.com/repos/kubernetes/kubernetes/pulls/90000/reviews \
    | jq '[.[].state] | unique'
[
  "APPROVED",
  "CHANGES_REQUESTED",
  "COMMENTED"
]

timeline-reviewed-event.state returns lowercase from the same PR (despite the spec's uppercase example: "CHANGES_REQUESTED"):

$ curl -s -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2022-11-28" \
    https://api.github.com/repos/kubernetes/kubernetes/issues/90000/timeline \
    | jq -r '[.[] | select(.event == "reviewed") | .state] | unique'
[
  "approved",
  "changes_requested",
  "commented"
]
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.