OpenAPI 3.2 Vocabulary
A vocabulary that defines the keywords that the OpenAPI Specification 3.2 adds to the JSON Schema 2020-12 dialect, covering polymorphism hints, XML representation, external documentation, and examples.
| Base Dialect | 2020-12 |
|---|---|
| URI | https://spec.openapis.org/oas/3.2/vocab/base |
| Specification | https://spec.openapis.org/oas/v3.2.1.html#base-vocabulary |
| Metaschema | https://spec.openapis.org/oas/3.2/meta/2026-02-26 |
| Also see |
To make use of this vocabulary, modify your metaschema to declare the use of this vocabulary using the $vocabulary keyword and evaluate its metaschema. If the vocabulary must be present for an implementation to proceed:
{
...
"$vocabulary": {
...
"https://spec.openapis.org/oas/3.2/vocab/base": true
},
"allOf": [
{ "$ref": "https://spec.openapis.org/oas/3.2/meta/2026-02-26" }
]
}Otherwise, if it is optional for implementations to understand this vocabulary to proceed:
{
...
"$vocabulary": {
...
"https://spec.openapis.org/oas/3.2/vocab/base": false
},
"allOf": [
{ "$ref": "https://spec.openapis.org/oas/3.2/meta/2026-02-26" }
]
}Keywords
| Keyword | Kind | Instance | Summary |
|---|---|---|---|
| discriminator | Other | Object | Hints at which of the schemas of an adjacent oneOf, anyOf, or allOf an object instance is expected to satisfy, without affecting the validation outcome. |
| xml | Other | Any | Describes how the instance that this schema applies to is represented when the payload is serialized as XML. |
| externalDocs | Other | Any | Points to an external resource that further documents the schema. |
| example | Other | Any | Declares a single example of an instance that this schema describes, superseded by the examples keyword. |