A guide to navigating the GitHub OpenAPI specification alongside the PyGithub codebase — how to look up schemas, paths, and understand the mapping between JSON and Python.

api.github.com.2022-11-28.20251114T1100.json

This is the full GitHub REST API OpenAPI 3.0 specification. It contains 737 paths and 875 schemas. The filename encodes the GitHub API version (2022-11-28) and the spec generation date.

{
  "paths": {
    "/repos/{owner}/{repo}/issues": { ... },   // 737 entries
    ...
  },
  "components": {
    "schemas": {                                // 875 entries
      "issue": { ... },
      "git-ref": { ... },
      ...
    },
    "parameters": { ... },   // reusable path/query params referenced via $ref
    "responses":  { ... },   // reusable HTTP responses referenced via $ref
    "examples":   { ... }    // reusable response examples referenced via $ref
  }
}

Each key under .paths is a URL template, e.g. /gists/{gist_id}/comments/{comment_id}. The value is an object keyed by HTTP verb (get, post, patch, put, delete). Each verb object contains:

"patch": {
  "summary": "Update a gist comment",
  "operationId": "gists/update-comment",
  "externalDocs": { "url": "https://docs.github.com/rest/gists/comments#update-a-gist-comment" },
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "properties": { "body": { "type": "string" } },
          "required": ["body"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": { "$ref": "#/components/schemas/gist-comment" }
        }
      }
    }
  }
}

Each key under .components.schemas is a schema name (kebab-case). The value is an OpenAPI Schema Object:

Schemas reference each other with "$ref": "#/components/schemas/schema-name". There are three common patterns:

1. Nested object — a field whose value is another full domain object:

   "user": { "$ref": "#/components/schemas/nullable-simple-user" }

   → _makeClassAttribute(github.NamedUser.NamedUser, attributes["user"])

2. Enum — a string field whose allowed values are defined in a shared schema:

   "author_association": { "$ref": "#/components/schemas/author-association" }

   where author-association is { "type": "string", "enum": [...] }. → _makeStringAttribute (PyGithub does not enforce the enum, just stores the string)

3. Inheritance via allOf — a schema that extends another:

   { "allOf": [ { "$ref": "#/components/schemas/base-schema" }, { "type": "object", "properties": { ... } } ] }

   → In PyGithub, properties from all members are merged into one class.

Two helper scripts extract information from the JSON file. Both read the JSON from stdin and take one argument.

Extracts a single path entry.

cat api.github.com.*.json | scripts/get-openapi-path.sh '/repos/{owner}/{repo}/git/refs/{ref}'

Internally runs: jq '.paths."/repos/{owner}/{repo}/git/refs/{ref}"'

Extracts a schema by its JSON Pointer path (the value in "The OpenAPI schema can be found at" comments).

cat api.github.com.*.json | scripts/get-openapi-schema.sh /components/schemas/autolink

The script transforms /components/schemas/autolink into a jq expression by replacing the leading / with ." and all subsequent / with ".", producing ."components"."schemas"."autolink", then runs jq '."components"."schemas"."autolink"'.

The schema path argument must start with / (not #/). Strip the leading # from $ref values before passing them to the script.

Every PyGithub class that has a corresponding OpenAPI schema documents it in the class docstring:

class Autolink(NonCompletableGithubObject):
    """
    The OpenAPI schema can be found at

    - /components/schemas/autolink
    """

Pass the listed path directly to get-openapi-schema.sh to retrieve the schema.

Every PyGithub method that makes an HTTP request documents it with :calls::

def edit(self, sha: str, force: Opt[bool] = NotSet) -> None:
    """
    :calls: `PATCH /repos/{owner}/{repo}/git/refs/{ref} <https://docs.github.com/...>`_
    """

The format is: VERB PATH "documentation URL" (RST hyperlink syntax). Pass the PATH to get-openapi-path.sh, then look up the verb key in the result.

Given a path from the OpenAPI spec, follow these four steps to identify (or design) the right PyGithub class and method.

The owning class is determined by the deepest named resource in the path.

B instances are always created by A (never via a B.get() — PyGithub has no such pattern). When B has its own class, its self-mutating methods (edit, delete) live on B. Read operations (get_B, get_Bs) always live on A.

The method name is derived from HTTP verb + path suffix after the resource ID. The tables below cover every established pattern.

Common parameter names follow the JSON field names verbatim (state, since, per_page, direction, sort).

Both use PUT, but the naming depends on whose perspective the method is written from:

• add_to_X(item) / remove_from_X(item) — used when the caller is managing a collection they own. E.g. AuthenticatedUser.add_to_starred(repo) — the user adds to their own starred-repos collection.

• set_X() / reset_X() — used when the resource itself has a boolean state flag. E.g. Gist.set_starred() — the gist has a "starred" state that the caller sets or clears.

Path: POST /repos/{owner}/{repo}/issues/{issue_number}/sub-issues Response: 201 with $ref: issue schema

1. Deepest resource: {issue_number} → Issue class
2. HTTP verb POST + suffix /sub-issues (creates items) → Issue.create_sub_issue(...)
3. Response is 201 with single $ref to issue → returns Issue instance
4. Check requestBody schema for required/optional fields → map to positional/Opt params

• Schema: /components/schemas/autolink
• Inherits NonCompletableGithubObject (no lazy loading — returned inline in list responses)
• No methods of its own; lifecycle is managed by Repository

{
  "title": "Autolink reference",
  "type": "object",
  "properties": {
    "id":             { "type": "integer" },
    "key_prefix":     { "type": "string" },
    "url_template":   { "type": "string" },
    "is_alphanumeric":{ "type": "boolean" },
    "updated_at":     { "type": "string", "format": "date-time", "nullable": true }
  },
  "required": ["id", "key_prefix", "url_template", "is_alphanumeric"]
}

The GET response schema is { "type": "array", "items": { "$ref": "#/components/schemas/autolink" } } — an array, so PyGithub wraps it in PaginatedList. The POST response schema is { "$ref": "#/components/schemas/autolink" } — a single object, so PyGithub returns one Autolink instance directly.

• Schema: /components/schemas/gist-comment
• Inherits CompletableGithubObject (supports lazy loading via self.url)
• Has delete() and edit() methods

{
  "title": "Gist Comment",
  "properties": {
    "id":               { "type": "integer" },
    "node_id":          { "type": "string" },
    "url":              { "type": "string", "format": "uri" },
    "body":             { "type": "string" },
    "user":             { "$ref": "#/components/schemas/nullable-simple-user" },
    "created_at":       { "type": "string", "format": "date-time" },
    "updated_at":       { "type": "string", "format": "date-time" },
    "author_association":{ "$ref": "#/components/schemas/author-association" }
  }
}

• user → _makeClassAttribute(github.NamedUser.NamedUser, ...)
• author_association resolves to an enum schema → _makeStringAttribute

• Schema: /components/schemas/git-ref
• Inherits CompletableGithubObject
• The object property is an inline nested object in the schema, not a $ref — PyGithub wraps it in the separate github.GitObject.GitObject class

{
  "title": "Git Reference",
  "properties": {
    "ref":     { "type": "string" },
    "node_id": { "type": "string" },
    "url":     { "type": "string", "format": "uri" },
    "object":  {
      "type": "object",
      "properties": {
        "type": { "type": "string" },
        "sha":  { "type": "string" },
        "url":  { "type": "string", "format": "uri" }
      }
    }
  }
}

PATCH requestBody has { "sha": string (required), "force": boolean (optional) } → matches edit(sha: str, force: Opt[bool] = NotSet).

JSON=api.github.com.*.json

# Look up a schema by path from the class docstring
cat $JSON | scripts/get-openapi-schema.sh /components/schemas/issue

# Look up a path from a :calls: docstring
cat $JSON | scripts/get-openapi-path.sh '/repos/{owner}/{repo}/issues'

# Resolve a $ref from a schema property (strip leading '#')
cat $JSON | scripts/get-openapi-schema.sh /components/schemas/nullable-simple-user

# List all paths for a given tag/category
jq '.paths | to_entries[] | select(.value | to_entries[].value.tags[]? == "gists") | .key' $JSON | sort -u

# List all schema names
jq '.components.schemas | keys[]' $JSON

# Extract all (VERB PATH) pairs from the spec
jq -r '.paths | to_entries[] | .key as $p | .value | to_entries[] |
  select(.key | test("^(get|post|put|patch|delete)$")) |
  [(.key | ascii_upcase), $p] | @tsv' $JSON | sort -u > /tmp/spec_paths.txt

# Extract all implemented (VERB PATH) pairs from :calls: docstrings
grep -rh ':calls:' github/ | grep -oP '(?<=:calls: `)[A-Z]+ [^\s<`]+' \
  | sed 's/ /\t/' | sort -u > /tmp/impl_paths.txt

# Find spec operations not yet implemented
comm -23 <(sort /tmp/spec_paths.txt) <(sort /tmp/impl_paths.txt)

As of the spec snapshot api.github.com.2022-11-28.20251114T1100.json:

• 1 111 total verb+path operations in the spec
• 535 implemented via :calls: docstrings in github/
• ~629 unimplemented (see OPENAPI.MISSING.md)

The gap is tracked in these files in the project root: