| name | openai-schema |
| description | This skill queries the OpenAI OpenAPI spec (~26k lines, 148 endpoints, 477 schemas) without loading the full file into context. Use when implementing or modifying Anthropic-to-OpenAI translation logic, checking OpenAI API field names/types, verifying schema shapes, or comparing request/response structures. Triggers on questions about OpenAI API structure, field types, endpoint parameters, or schema definitions. |
OpenAI API Schema Query
Query the OpenAI OpenAPI spec (v2.3.0, 148 endpoints, 477 schemas) for specific endpoints, schemas, and fields. The full spec is ~1.4MB/26k lines; this skill provides targeted lookups without loading it all into context.
Setup
The query script requires PyYAML via the project venv:
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py <command>
If the venv does not exist:
python3 -m venv scripts/.venv && scripts/.venv/bin/pip install pyyaml
The spec is auto-downloaded and cached to scripts/.cache/openapi.yaml on first run.
Commands
List available API tag groups
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py tags
List endpoints (optionally filter by tag or path)
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py endpoints --filter chat
Show endpoint detail by operationId or path
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py endpoint createChatCompletion
Returns: method, path, tags, summary, parameters, request body ref, response refs.
Show schema detail with configurable depth
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py schema CreateChatCompletionRequest --depth 2
--depth 0: schema composition only (allOf/oneOf refs)--depth 1 (default): properties with types and refs--depth 2: expand referenced schemas one level deeper
Supports case-insensitive substring matching: schema chatcompletion finds all matching schemas.
Search by regex pattern
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py search "tool" --deep
Searches schema names, endpoint paths, and operationIds. --deep also searches property names within schemas.
Update cached spec
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py update
Re-downloads the spec from GitHub, replacing the local cache. Reports version, endpoint count, and schema count.
Compare schema fields
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py diff CreateChatCompletionResponse
scripts/.venv/bin/python3 .Codex/skills/openai-schema/scripts/query-openai-schema.py diff CreateChatCompletionRequest --compare CreateChatCompletionResponse
Without --compare: lists all fields. With --compare: shows shared, source-only, and target-only fields.
Condensed spec generation
For bulk output (e.g., to include in context or save to file), use the condenser script:
scripts/.venv/bin/python3 scripts/condense-openapi.py --tag Chat -o docs/openai-spec-condensed.yaml
scripts/.venv/bin/python3 scripts/condense-openapi.py --tag Chat --tag Responses -o docs/openai-spec-condensed.yaml
scripts/.venv/bin/python3 scripts/condense-openapi.py -o docs/openai-spec-condensed.yaml
Workflow
When working on translation logic in this project:
- Identify the OpenAI type to look up (check
crates/translator/src/openai/ for the Rust type name)
- Query the schema to get the canonical field list, types, and required fields
- Compare with the Rust struct to find gaps or mismatches
- Check the endpoint if parameter or request body structure is unclear
For translation gap analysis, use diff --compare to compare request vs response schemas, or compare the OpenAI schema fields against the Anthropic types in crates/translator/src/anthropic/.
Available tags
Assistants, Audio, Audit Logs, Batch, Certificates, Chat, Completions, Embeddings, Evals, Files, Fine-tuning, Images, Invites, Models, Moderations, Projects, Realtime, Responses, Uploads, Usage, Users, Vector stores.
