openapi-specification-v3.2▌
hairyf/skills · updated Apr 8, 2026
Agent-oriented reference for the OpenAPI Specification 3.2.0. Use when editing, generating, or validating OpenAPI descriptions (OAD).
OpenAPI Specification 3.2
Agent-oriented reference for the OpenAPI Specification 3.2.0. Use when editing, generating, or validating OpenAPI descriptions (OAD).
When to Use
- Authoring or updating OpenAPI 3.2 YAML/JSON documents
- Resolving
$ref,$self, and relative URIs in multi-document OADs - Describing paths, operations, parameters (query/path/header/cookie/querystring), request body, and responses
- Using Schema Objects (JSON Schema Draft 2020-12 dialect), components, and references
- Configuring security schemes (apiKey, http, mutualTLS, oauth2, openIdConnect) and requirements
- Working with media types, encoding (form, multipart), and examples (dataValue/serializedValue/externalValue)
Core References
| Topic | Description | Reference |
|---|---|---|
| OpenAPI Object | Root object, openapi, $self, info, servers, paths, webhooks, components, security, tags | core-openapi-object |
| Format & Structure | JSON/YAML, case sensitivity, rich text, OAD structure, parsing, base URI | core-format-and-structure |
| Fixed & Patterned Fields | Fixed vs patterned fields, paths keys, components keys, extensions (x-) | core-fixed-patterned-fields |
| Info & Metadata | Info, Contact, License objects | core-info-metadata |
| Server | Server Object, Server Variable, URL templating | core-server |
| Paths & Operations | Paths Object, Path Item, Operation Object, additionalOperations, query | paths-and-operations |
| Path Templating | Path templating, path parameters, matching, ABNF | core-path-templating |
| Parameters | Parameter Object, in (path/query/header/cookie/querystring), style, schema vs content | parameters |
| Request Body & Media Type | Request Body, Media Type Object, sequential media types, itemSchema | request-body-and-media-type |
| Encoding Object | Encoding by name/position, contentType, style, explode, form, multipart | core-encoding-object |
| Media Types | Content keys, media type ranges, OpenAPI Media Type Registry | core-media-types |
| Responses | Responses Object, Response Object, headers, content, links | responses |
| HTTP Status Codes | Response keys, default, 1XX–5XX range with X | core-http-status-codes |
| Schema & Components | Schema Object (JSON Schema 2020-12), Components, $ref resolution | schema-and-components |
| Schema JSON Schema Keywords | JSON Schema 2020-12 keywords and OAS extensions in Schema | schema-json-schema-keywords |
| Schema Composition & Polymorphism | allOf, oneOf, anyOf, discriminator | schema-composition-polymorphism |
| Data Types & Formats | JSON Schema types, format keyword, OAS dialect | core-data-types-and-formats |
| Discriminator & XML | Discriminator Object, XML Object (nodeType, name, namespace) | core-discriminator-and-xml |
| Components Reuse | Reusing parameters, responses, schemas via $ref | components-reuse |
| Reference Object | $ref, summary/description override, resolution rules | core-reference-object |
| Header Object | Response/multipart headers, style simple, Set-Cookie, Link | core-header-object |
| Example Object | dataValue, serializedValue, value, externalValue, Working with Examples | core-example-object |
| Tag & External Docs | Tag Object, External Documentation Object, parent, kind | core-tags-and-external-docs |
| Link Object | operationRef, operationId, parameters, requestBody | core-link-object |
| Runtime Expressions | $request, $response, $url, $method, ABNF, Link/Callback usage | core-runtime-expressions |
| Security | Security Scheme, OAuth Flows, Security Requirement Object | security |
| Security Scheme Types | apiKey, http (basic/bearer), mutualTLS, oauth2, openIdConnect | security-scheme-types |
| Security Requirement Object | OR/AND semantics, {} optional, [] clear, scopes | security-requirement-object |
| OAuth2 Flows | OAuth Flows Object, OAuth Flow Object, authorizationCode, deviceAuthorization | security-oauth2-flows |
| Callbacks & Webhooks | Callback Object, webhooks | callbacks-and-webhooks |
| Extensions | Specification extensions (x-), extension registries | advanced-extensions |
Best Practices
| Topic | Description | Reference |
|---|---|---|
| Spec Authoring | operationId, tags, $self, components reuse, responses, security | best-practices-spec-authoring |
Advanced
| Topic | Description | Reference |
|---|---|---|
| Base URI & Resolution | $self, retrieval URI, reference resolution, parsing guidance | advanced-base-uri-and-resolution |
| Security Filtering | Empty Paths/Path Item, Security Considerations | advanced-security-filtering |
Key Points
- OAS 3.2 root uses
openapi: 3.2.0; at least one ofcomponents,paths, orwebhooksMUST be present. $selfprovides the document's base URI for reference resolution; use it in multi-document OADs.- Schema Object is a superset of JSON Schema Draft 2020-12; empty schema =
true, none =false. - Parameter: use either
schema+styleorcontent(one Media Type);in: "querystring"requirescontent. - Security at root is OR (one of the Security Requirement Objects); per-operation overrides;
{}= optional.
Ratings
4.6★★★★★25 reviews- ★★★★★Isabella Sharma· Dec 20, 2024
Registry listing for openapi-specification-v3.2 matched our evaluation — installs cleanly and behaves as described in the markdown.
- ★★★★★Isabella Flores· Dec 16, 2024
openapi-specification-v3.2 fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.
- ★★★★★Dhruvi Jain· Dec 12, 2024
We added openapi-specification-v3.2 from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.
- ★★★★★Aarav Yang· Nov 11, 2024
Solid pick for teams standardizing on skills: openapi-specification-v3.2 is focused, and the summary matches what you get after install.
- ★★★★★Henry Mehta· Nov 7, 2024
We added openapi-specification-v3.2 from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.
- ★★★★★Oshnikdeep· Nov 3, 2024
openapi-specification-v3.2 fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.
- ★★★★★Mia Rahman· Oct 26, 2024
Solid pick for teams standardizing on skills: openapi-specification-v3.2 is focused, and the summary matches what you get after install.
- ★★★★★Ganesh Mohane· Oct 22, 2024
Registry listing for openapi-specification-v3.2 matched our evaluation — installs cleanly and behaves as described in the markdown.
- ★★★★★Aarav Haddad· Oct 2, 2024
We added openapi-specification-v3.2 from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.
- ★★★★★Aisha Patel· Jul 23, 2024
openapi-specification-v3.2 has been reliable in day-to-day use. Documentation quality is above average for community skills.
showing 1-10 of 25