openapi-specification-v3.2

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 of components, paths, or webhooks MUST be present.
• $self provides 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+style or content (one Media Type); in: "querystring" requires content.
• Security at root is OR (one of the Security Requirement Objects); per-operation overrides; {} = optional.