openai / openai/openai-openapi

Make `Responses` tagging complete and consistent across the OpenAPI document

Open
#561 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement specification
Dominant language
No language data
Stars
2.5k
Forks
527
Avg merge
1h 46m
Merged PRs (30d)
2

Description

Responses API operations are not tagged consistently in openapi.yaml.

Most Responses API operations use:

tags:
  - Responses

However:

  1. Responses is not declared in the root-level tags array.
  2. Some Responses API operations do not contain the Responses operation tag.

This makes tag-based filtering incomplete and can cause documentation tools to organize the undeclared tag inconsistently.

Affected operations

The following stable operations have x-oaiMeta.group: responses but no tags property:

POST /responses/input_tokens
POST /responses/compact

The corresponding beta path entries also appear to be missing the tag:

POST /responses/input_tokens?beta=true
POST /responses/compact?beta=true

By comparison, the other Responses API operations use:

tags:
  - Responses
Root-level tag declaration

The document declares tags such as Chat, Audio, and Embeddings in the root-level tags array, but does not declare Responses, even though many operations use that tag.

A declaration similar to the following would make the tag catalog complete:

tags:
  - name: Responses
    description: Create and manage model responses.
Why this matters

Consumers commonly use operation tags to:

  • Generate API-specific documentation.
  • Generate partial clients.
  • Group operations in API explorers.
  • Extract only the endpoints belonging to a particular API family.
  • Reduce the size of the specification before processing it.

At present, filtering for operations tagged Responses silently excludes the input-token-counting and compaction endpoints.

Minimal reproduction
import yaml

with open("openapi.yaml", encoding="utf-8") as file:
    spec = yaml.safe_load(file)

declared_tags = {
    tag["name"]
    for tag in spec.get("tags", [])
}

used_tags = set()
untagged_response_operations = []

http_methods = {
    "get", "post", "put", "patch",
    "delete", "head", "options", "trace",
}

for path, path_item in spec.get("paths", {}).items():
    for method, operation in path_item.items():
        if method.lower() not in http_methods:
            continue

        tags = operation.get("tags", [])
        used_tags.update(tags)

        group = operation.get("x-oaiMeta", {}).get("group")
        if group == "responses" and "Responses" not in tags:
            untagged_response_operations.append(
                f"{method.upper()} {path}"
            )

print("Responses declared:", "Responses" in declared_tags)
print("Responses used:", "Responses" in used_tags)
print("Untagged Responses operations:")
print("\n".join(untagged_response_operations))
Current behavior

The script reports that:

  • Responses is used but not declared.
  • Some operations in the responses metadata group do not use the Responses tag.
Expected behavior
  • Responses is included in the root-level tags array.
  • Every Responses API operation includes tags: [Responses].
  • Stable and beta variants follow the same tagging convention.
Suggested acceptance criteria
  • Add a root-level declaration for the Responses tag.
  • Add the Responses tag to every operation whose x-oaiMeta.group is responses.
  • Add a CI check ensuring operation tags and x-oaiMeta.group values remain consistent.
  • Add a CI check warning when an operation uses an undeclared root-level tag.

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.

Research direction

Start in openapi.yaml by comparing the root-level tags array with operations whose x-oaiMeta.group is responses, especially the stable and beta input_tokens and compact paths. Run the Python reproduction from the issue to verify undeclared and untagged operations. Done means every Responses operation is tagged, Responses is declared at the root, and CI checks the stated tag consistency rules.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.