1---2name: openapi-specification-v3-23description: OpenAPI Specification 3.2 — write and interpret OpenAPI descriptions (OAD), paths, operations, parameters, request/response, schema (JSON Schema 2020-12), security, and extensions. Use when authoring or validating OpenAPI 3.2 documents.4---5
6# OpenAPI Specification 3.2
7
8Agent-oriented reference for the OpenAPI Specification 3.2.0. Use when editing, generating, or validating OpenAPI descriptions (OAD).
9
10## When to Use
11
12- Authoring or updating OpenAPI 3.2 YAML/JSON documents
13- Resolving `$ref`, `$self`, and relative URIs in multi-document OADs
14- Describing paths, operations, parameters (query/path/header/cookie/querystring), request body, and responses
15- Using Schema Objects (JSON Schema Draft 2020-12 dialect), components, and references
16- Configuring security schemes (apiKey, http, mutualTLS, oauth2, openIdConnect) and requirements
17- Working with media types, encoding (form, multipart), and examples (dataValue/serializedValue/externalValue)
18
19## Core References
20
21| Topic | Description | Reference |
22|-------|-------------|-----------|
23| OpenAPI Object | Root object, openapi, $self, info, servers, paths, webhooks, components, security, tags | [core-openapi-object](references/core-openapi-object.md) |
24| Format & Structure | JSON/YAML, case sensitivity, rich text, OAD structure, parsing, base URI | [core-format-and-structure](references/core-format-and-structure.md) |
25| Fixed & Patterned Fields | Fixed vs patterned fields, paths keys, components keys, extensions (x-) | [core-fixed-patterned-fields](references/core-fixed-patterned-fields.md) |
26| Info & Metadata | Info, Contact, License objects | [core-info-metadata](references/core-info-metadata.md) |
27| Server | Server Object, Server Variable, URL templating | [core-server](references/core-server.md) |
28| Paths & Operations | Paths Object, Path Item, Operation Object, additionalOperations, query | [paths-and-operations](references/paths-and-operations.md) |
29| Path Templating | Path templating, path parameters, matching, ABNF | [core-path-templating](references/core-path-templating.md) |
30| Parameters | Parameter Object, in (path/query/header/cookie/querystring), style, schema vs content | [parameters](references/parameters.md) |
31| Request Body & Media Type | Request Body, Media Type Object, sequential media types, itemSchema | [request-body-and-media-type](references/request-body-and-media-type.md) |
32| Encoding Object | Encoding by name/position, contentType, style, explode, form, multipart | [core-encoding-object](references/core-encoding-object.md) |
33| Media Types | Content keys, media type ranges, OpenAPI Media Type Registry | [core-media-types](references/core-media-types.md) |
34| Responses | Responses Object, Response Object, headers, content, links | [responses](references/responses.md) |
35| HTTP Status Codes | Response keys, default, 1XX–5XX range with X | [core-http-status-codes](references/core-http-status-codes.md) |
36| Schema & Components | Schema Object (JSON Schema 2020-12), Components, $ref resolution | [schema-and-components](references/schema-and-components.md) |
37| Schema JSON Schema Keywords | JSON Schema 2020-12 keywords and OAS extensions in Schema | [schema-json-schema-keywords](references/schema-json-schema-keywords.md) |
38| Schema Composition & Polymorphism | allOf, oneOf, anyOf, discriminator | [schema-composition-polymorphism](references/schema-composition-polymorphism.md) |
39| Data Types & Formats | JSON Schema types, format keyword, OAS dialect | [core-data-types-and-formats](references/core-data-types-and-formats.md) |
40| Discriminator & XML | Discriminator Object, XML Object (nodeType, name, namespace) | [core-discriminator-and-xml](references/core-discriminator-and-xml.md) |
41| Components Reuse | Reusing parameters, responses, schemas via $ref | [components-reuse](references/components-reuse.md) |
42| Reference Object | $ref, summary/description override, resolution rules | [core-reference-object](references/core-reference-object.md) |
43| Header Object | Response/multipart headers, style simple, Set-Cookie, Link | [core-header-object](references/core-header-object.md) |
44| Example Object | dataValue, serializedValue, value, externalValue, Working with Examples | [core-example-object](references/core-example-object.md) |
45| Tag & External Docs | Tag Object, External Documentation Object, parent, kind | [core-tags-and-external-docs](references/core-tags-and-external-docs.md) |
46| Link Object | operationRef, operationId, parameters, requestBody | [core-link-object](references/core-link-object.md) |
47| Runtime Expressions | $request, $response, $url, $method, ABNF, Link/Callback usage | [core-runtime-expressions](references/core-runtime-expressions.md) |
48| Security | Security Scheme, OAuth Flows, Security Requirement Object | [security](references/security.md) |
49| Security Scheme Types | apiKey, http (basic/bearer), mutualTLS, oauth2, openIdConnect | [security-scheme-types](references/security-scheme-types.md) |
50| Security Requirement Object | OR/AND semantics, {} optional, [] clear, scopes | [security-requirement-object](references/security-requirement-object.md) |
51| OAuth2 Flows | OAuth Flows Object, OAuth Flow Object, authorizationCode, deviceAuthorization | [security-oauth2-flows](references/security-oauth2-flows.md) |
52| Callbacks & Webhooks | Callback Object, webhooks | [callbacks-and-webhooks](references/callbacks-and-webhooks.md) |
53| Extensions | Specification extensions (x-), extension registries | [advanced-extensions](references/advanced-extensions.md) |
54
55## Best Practices
56
57| Topic | Description | Reference |
58|-------|-------------|-----------|
59| Spec Authoring | operationId, tags, $self, components reuse, responses, security | [best-practices-spec-authoring](references/best-practices-spec-authoring.md) |
60
61## Advanced
62
63| Topic | Description | Reference |
64|-------|-------------|-----------|
65| Base URI & Resolution | $self, retrieval URI, reference resolution, parsing guidance | [advanced-base-uri-and-resolution](references/advanced-base-uri-and-resolution.md) |
66| Security Filtering | Empty Paths/Path Item, Security Considerations | [advanced-security-filtering](references/advanced-security-filtering.md) |
67
68## Key Points
69
70- OAS 3.2 root uses `openapi: 3.2.0`; at least one of `components`, `paths`, or `webhooks` MUST be present.
71- `$self` provides the document's base URI for reference resolution; use it in multi-document OADs.
72- Schema Object is a superset of JSON Schema Draft 2020-12; empty schema = `true`, none = `false`.
73- Parameter: use either `schema`+`style` or `content` (one Media Type); `in: "querystring"` requires `content`.
74- Security at root is OR (one of the Security Requirement Objects); per-operation overrides; `{}` = optional.
75
76<!--
77Source: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.2.0.md
78-->
hairyf