Repository navigation
[Schema Inaccuracy] Batch of 29 description, parameter, and summary text/Markdown defects across api.github.com, ghec, and ghes specs #7420
Description
Schema Inaccuracy
While building and validating a multi-platform OpenAPI consumer against descriptions/api.github.com/api.github.com.json, descriptions/ghec/ghec.json, and descriptions/ghes-3.20/ghes-3.20.json (verified at commit 78edb1e2af8b511d88a0be137b69622a13a2b137), we identified 29 text and Markdown formatting inaccuracies (27 distinct root defects) across operation descriptions, parameter descriptions, request-body schema property descriptions, response descriptions, and operation summaries.
To avoid opening 29 separate micro-issues, we have consolidated them below into seven categories with exact operationIds, HTTP routes, OpenAPI JSON pointers, current verbatim strings, and expected corrections:
- Unclosed
**bold Markdown spans (1 shared property description across 2 operations) - Doubled adjacent words in prose (7 operations)
- Malformed Markdown links and stray/unclosed quotes (5 operations)
- Doubled
/enterprise-cloud@latest/enterprise-cloud@latest/path segments inghec.jsondocs URLs (3 operations) - Typos, missing verbs, and grammar defects (6 operations)
- Copy-paste / sibling-endpoint wording mismatches (2 operations)
- Formatting and punctuation inconsistencies (4 operations)
Expected
1. Unclosed ** bold Markdown spans (2 operations)
Both operations inline or reference the use_squash_pr_title_as_default request-body property, whose description opens a ** bold span at the deprecation notice and never closes it:
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim) | Expected |
|---|---|---|---|---|---|
| 1a | api.github.com, ghec, ghes |
repos/update (PATCH /repos/{owner}/{repo}) |
/paths/~1repos~1{owner}~1{repo}/patch/requestBody/content/application~1json/schema/properties/use_squash_pr_title_as_default/description |
Either \true` to allow squash-merge commits to use pull request title, or `false` to use commit message. **This property is closing down. Please use `squash_merge_commit_title` instead.` |
Close the trailing bold span: ...Please use \squash_merge_commit_title` instead.**` |
| 1b | api.github.com, ghec, ghes |
repos/create-in-org (POST /orgs/{org}/repos) |
/paths/~1orgs~1{org}~1repos/post/requestBody/content/application~1json/schema/properties/use_squash_pr_title_as_default/description |
Either \true` to allow squash-merge commits to use pull request title, or `false` to use commit message. **This property is closing down. Please use `squash_merge_commit_title` instead.` |
Close the trailing bold span: ...Please use \squash_merge_commit_title` instead.**` |
2. Doubled adjacent words in prose (7 operations)
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim excerpt) | Expected |
|---|---|---|---|---|---|
| 2a | api.github.com, ghec, ghes |
orgs/assign-role-to-user (PUT /orgs/{org}/organization-roles/users/{username}/{role_id}) |
/paths/~1orgs~1{org}~1organization-roles~1users~1{username}~1{role_id}/put/description |
Organization roles cannot be assigned to a user if an Enterprise Managed User (EMU) is enabled enabled. |
...is enabled. (remove duplicate enabled) |
| 2b | ghes |
enterprise-admin/init-instance-configuration-with-license (POST /manage/v1/config/init) |
/paths/~1manage~1v1~1config~1init/post/description |
Remember that a settings initialization can can take quite some time to complete. |
...initialization can take quite some time... (remove duplicate can) |
| 2c | ghes |
enterprise-admin/upload-license (PUT /manage/v1/config/license) |
/paths/~1manage~1v1~1config~1license/put/description |
Remember that a settings synchronization can can take quite some time to complete. |
...synchronization can take quite some time... (remove duplicate can) |
| 2d | api.github.com, ghec, ghes |
reactions/delete-for-release (DELETE /repos/{owner}/{repo}/releases/{release_id}/reactions/{reaction_id}) |
/paths/~1repos~1{owner}~1{repo}~1releases~1{release_id}~1reactions~1{reaction_id}/delete/description |
>**Note:** You can also specify a repository by \repository_id` using the route `DELETE delete /repositories/:repository_id/releases/:release_id/reactions/:reaction_id`.` |
...using the route \DELETE /repositories/:repository_id/releases/:release_id/reactions/:reaction_id`.(remove duplicatedelete`) |
| 2e | api.github.com, ghec, ghes |
reactions/delete-for-issue-comment (DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}/reactions/{reaction_id}) |
/paths/~1repos~1{owner}~1{repo}~1issues~1comments~1{comment_id}~1reactions~1{reaction_id}/delete/description |
>**Note:** You can also specify a repository by \repository_id` using the route `DELETE delete /repositories/:repository_id/issues/comments/:comment_id/reactions/:reaction_id`.` |
...using the route \DELETE /repositories/:repository_id/issues/comments/:comment_id/reactions/:reaction_id`.(remove duplicatedelete`) |
| 2f | api.github.com, ghec, ghes |
security-advisories/get-repository-advisory (GET /repos/{owner}/{repo}/security-advisories/{ghsa_id}) |
/paths/~1repos~1{owner}~1{repo}~1security-advisories~1{ghsa_id}/get/description |
Anyone can access any published security advisory on a public repository. Authenticate to to access an unpublished security advisory... |
...Authenticate to access an unpublished security advisory... (remove duplicate to) |
| 2g | api.github.com, ghec, ghes |
security-advisories/list-repository-advisories (GET /repos/{owner}/{repo}/security-advisories) |
/paths/~1repos~1{owner}~1{repo}~1security-advisories/get/description |
Anyone can access any published security advisory on a public repository. Authenticate to to access an unpublished security advisory... |
...Authenticate to access an unpublished security advisory... (remove duplicate to) |
3. Malformed Markdown links and stray/unclosed quotes (5 operations)
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim excerpt) | Expected |
|---|---|---|---|---|---|
| 3a | api.github.com, ghec, ghes |
orgs/get-webhook (GET /orgs/{org}/hooks/{hook_id}) |
/paths/~1orgs~1{org}~1hooks~1{hook_id}/get/description |
To get only the webhook \config` properties, see "Get a webhook configuration for an organization.` |
Add the missing closing quote " after ).: see "[Get a webhook configuration for an organization](/rest/orgs/webhooks#get-a-webhook-configuration-for-an-organization)." |
| 3b | api.github.com, ghec, ghes |
orgs/get-webhook-config-for-org (GET /orgs/{org}/hooks/{hook_id}/config) |
/paths/~1orgs~1{org}~1hooks~1{hook_id}~1config/get/description |
use "[Get an organization webhook ](/rest/orgs/webhooks#get-an-organization-webhook)." |
Remove the trailing space inside the Markdown link text: use "[Get an organization webhook](/rest/orgs/webhooks#get-an-organization-webhook)." |
| 3c | api.github.com, ghec, ghes |
orgs/update-webhook-config-for-org (PATCH /orgs/{org}/hooks/{hook_id}/config) |
/paths/~1orgs~1{org}~1hooks~1{hook_id}~1config/patch/description |
use "[Update an organization webhook ](/rest/orgs/webhooks#update-an-organization-webhook)." |
Remove the trailing space inside the Markdown link text: use "[Update an organization webhook](/rest/orgs/webhooks#update-an-organization-webhook)." |
| 3d | api.github.com, ghec, ghes |
actions/approve-workflow-run (POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve) |
/paths/~1repos~1{owner}~1{repo}~1actions~1runs~1{run_id}~1approve/post/description |
For more information, see ["Approving workflow runs from public forks](https://docs.github.com/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks)." |
Move the opening " outside [: see "[Approving workflow runs from public forks](https://docs.github.com/actions/managing-workflow-runs/approving-workflow-runs-from-public-forks)." |
| 3e | api.github.com, ghec, ghes |
repos/update-branch-protection (PUT /repos/{owner}/{repo}/branches/{branch}/protection) |
/paths/~1repos~1{owner}~1{repo}~1branches~1{branch}~1protection/put/requestBody/content/application~1json/schema/properties/allow_force_pushes/description |
Permits force pushes to the protected branch by anyone with write access to the repository. Set to \true` to allow force pushes. Set to `false` or `null` to block force pushes. Default: `false`. For more information, see "Enabling force pushes to a protected branch." Specify a non-empty `allow_force_pushes.users` or `allow_force_pushes.teams` or `allow_force_pushes.apps` object to specify who can do so."` |
Remove the stray trailing " at the very end of the sentence (...specify who can do so.) |
4. Doubled /enterprise-cloud@latest/enterprise-cloud@latest/ URL prefix in ghec.json (3 operations)
In descriptions/ghec/ghec.json, the version prefix rewriter produces /enterprise-cloud@latest/enterprise-cloud@latest/ on links whose source already carried /enterprise-cloud@latest/:
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim excerpt) | Expected |
|---|---|---|---|---|---|
| 4a | ghec |
teams/list (GET /orgs/{org}/teams) |
/components/parameters/team-type/description |
For more information, see "[What kind of team should I use?](https://docs.github.com/enterprise-cloud@latest/enterprise-cloud@latest/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise#what-kind-of-team-should-i-use)" |
Single /enterprise-cloud@latest/ prefix: https://docs.github.com/enterprise-cloud@latest/admin/concepts/enterprise-fundamentals/teams-in-an-enterprise#what-kind-of-team-should-i-use |
| 4b | ghec |
users/get-by-id (GET /user/{account_id}) |
/paths/~1user~1{account_id}/get/description |
If you are requesting information about an [Enterprise Managed User](https://docs.github.com/enterprise-cloud@latest/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users)... |
Single /enterprise-cloud@latest/ prefix: https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users |
| 4c | ghec |
users/get-by-username (GET /users/{username}) |
/paths/~1users~1{username}/get/description |
If you are requesting information about an [Enterprise Managed User](https://docs.github.com/enterprise-cloud@latest/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users)... |
Single /enterprise-cloud@latest/ prefix: https://docs.github.com/enterprise-cloud@latest/admin/managing-iam/understanding-iam-for-enterprises/about-enterprise-managed-users |
5. Typos, missing verbs, and grammar defects (6 operations)
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim excerpt) | Expected |
|---|---|---|---|---|---|
| 5a | api.github.com, ghec, ghes |
teams/check-permissions-for-repo-in-org (GET /orgs/{org}/teams/{team_slug}/repos/{owner}/{repo}) |
/paths/~1orgs~1{org}~1teams~1{team_slug}~1repos~1{owner}~1{repo}/get/responses/204/description |
Response if repository is managed by this team and the \Accept` header is not provded with the custom media type` |
Fix typo provded → provided |
| 5b | api.github.com, ghec, ghes |
teams/remove-member-legacy (DELETE /teams/{team_id}/members/{username}) |
/paths/~1teams~1{team_id}~1members~1{username}/delete/responses/404/description |
Not Found if team synchronization is setup |
Use verb phrase is set up instead of noun setup |
| 5c | ghec |
enterprise-admin/provision-scim-enterprise-user (POST /scim/v2/enterprises/{enterprise}/Users) |
/paths/~1scim~1v2~1enterprises~1{enterprise}~1Users/post/requestBody/content/application~1scim+json/schema/properties/active/description |
Whether the user active in the IdP. |
Insert missing verb: Whether the user is active in the IdP. |
| 5d | ghec |
enterprise-admin/set-scim-information-for-provisioned-enterprise-user (PUT /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}) |
/paths/~1scim~1v2~1enterprises~1{enterprise}~1Users~1{scim_user_id}/put/requestBody/content/application~1scim+json/schema/properties/active/description |
Whether the user active in the IdP. |
Insert missing verb: Whether the user is active in the IdP. |
| 5e | api.github.com, ghec, ghes |
orgs/create-artifact-deployment-record (POST /orgs/{org}/artifacts/metadata/deployment-record) |
/paths/~1orgs~1{org}~1artifacts~1metadata~1deployment-record/post/requestBody/content/application~1json/schema/properties/deployment_id/description |
A uniqe identifier for the deployment. |
Fix typo uniqe → unique |
| 5f | api.github.com, ghec |
orgs/update-pat-access (POST /orgs/{org}/personal-access-tokens/{pat_id}) |
/paths/~1orgs~1{org}~1personal-access-tokens~1{pat_id}/post/description |
Updates the access a fine-grained personal access token has to organization resources. Limited to revoking the token's existing access. Limited to revoking a token's existing access. |
Remove duplicated trailing sentence (Limited to revoking a token's existing access.) |
6. Copy-paste and sibling-endpoint wording mismatches (2 operations)
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim excerpt) | Expected |
|---|---|---|---|---|---|
| 6a | ghec |
copilot/remove-copilot-for-enterprise-teams (DELETE /enterprises/{enterprise}/copilot/billing/selected_enterprise_teams) |
/paths/~1enterprises~1{enterprise}~1copilot~1billing~1selected_enterprise_teams/delete/requestBody/content/application~1json/schema/properties/selected_enterprise_teams/description |
List of enterprise team names within the enterprise to grant access to GitHub Copilot. |
This is a DELETE endpoint that revokes access; description should say ...to revoke access to GitHub Copilot. (or ...to remove from the GitHub Copilot subscription.) |
| 6b | ghec, ghes |
actions/create-self-hosted-runner-group-for-enterprise (POST /enterprises/{enterprise}/actions/runner-groups) |
/paths/~1enterprises~1{enterprise}~1actions~1runner-groups/post/requestBody/content/application~1json/schema/properties/visibility/description |
Visibility of a runner group. You can select all organizations or select individual organization. Can be one of: \all`, `selected`.` |
Align with sibling PATCH /enterprises/{enterprise}/actions/runner-groups/{runner_group_id} which uses plural ...select individual organizations. |
7. Formatting and punctuation inconsistencies (4 operations)
| # | Spec(s) | operationId (Method Path) |
JSON Pointer | Current (verbatim excerpt) | Expected |
|---|---|---|---|---|---|
| 7a | api.github.com, ghec, ghes |
repos/enable-lfs-for-repo (PUT /repos/{owner}/{repo}/lfs) |
/paths/~1repos~1{owner}~1{repo}~1lfs/put/responses/403/description |
Forbidden — <owner> is an organization and has disabled Git LFS for its repositories... |
Wrap <owner> in backticks (\`or`{owner}`) so Markdown renderers do not strip` as an unknown raw HTML tag |
| 7b | api.github.com, ghec |
orgs/list-attestation-repositories (GET /orgs/{org}/attestations/repositories) |
/paths/~1orgs~1{org}~1attestations~1repositories/get/description |
List repositories owned by the provided organization that have created at least one attested artifact\nResults will be sorted in ascending order by repository ID |
Add missing period after artifact. and ID. |
| 7c | api.github.com, ghec, ghes |
orgs/delete-organization-role (DELETE /orgs/{org}/organization-roles/{role_id}) |
/paths/~1orgs~1{org}~1organization-roles~1{role_id}/delete/summary |
Delete a custom organization role. |
Remove trailing period (Delete a custom organization role) to match the summary convention across other REST operations |
| 7d | ghec |
enterprise-admin/delete-scim-user-from-enterprise (DELETE /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}) |
/paths/~1scim~1v2~1enterprises~1{enterprise}~1Users~1{scim_user_id}/delete/description |
**Note:** If the user you are deleting is a member of one or more organizations in your enterprise, removing them from the enterprise, you must also remove them from those organizations. |
Fix ungrammatical clause and double space after comma |
Reproduction Steps
Each entry above can be inspected directly against github/rest-api-description@78edb1e2af8b511d88a0be137b69622a13a2b137 using jq:
# Example 1: Unclosed bold span (1a / 1b)
jq -r '.paths["/repos/{owner}/{repo}"].patch.requestBody.content["application/json"].schema.properties.use_squash_pr_title_as_default.description' \
descriptions/api.github.com/api.github.com.json
# Example 2: Doubled word "enabled enabled" (2a)
jq -r '.paths["/orgs/{org}/organization-roles/users/{username}/{role_id}"].put.description' \
descriptions/api.github.com/api.github.com.json
# Example 3: Doubled /enterprise-cloud@latest/enterprise-cloud@latest/ URL segment in ghec.json (4a)
jq -r '.components.parameters["team-type"].description' \
descriptions/ghec/ghec.json
# Example 4: Misleading DELETE property description (6a)
jq -r '.paths["/enterprises/{enterprise}/copilot/billing/selected_enterprise_teams"].delete.requestBody.content["application/json"].schema.properties.selected_enterprise_teams.description' \
descriptions/ghec/ghec.json
Activity