Use this file to discover all available pages before exploring further.
This page covers new and changed features in OpenAPI 3.1 (3.1.0–3.1.2) relative to OAS 3.0. Only deltas are documented — for base feature coverage, see the OAS 3.0 page.
OAS 3.1 aligns data types with JSON Schema Draft 2020-12. The primitive format table is unchanged from OAS 3.0.
Field
Support
Behavior
type as array
["string", "null"] maps to str | None, ["string", "integer"] maps to str | int
contentEncoding
base64/base64url generates format: byte validation. base16/base32 stored as metadata. Raw value surfaced in Field(json_schema_extra=...) for LLM visibility
contentMediaType
Surfaced in Field(json_schema_extra=...) alongside contentEncoding and format
New identifier field for SPDX license expressions.
Field
Support
Behavior
identifier
SPDX license expression (e.g., "Apache-2.0"); mutually exclusive with url. Rendered in generated server docstring and README. Takes precedence over url when present
Generates @model_validator with conditional logic. When if matches, then constraints enforced; otherwise else constraints
dependentRequired
Generates @model_validator enforcing “if field X present, fields Y and Z required”
const
Generates Literal[value] type annotation
dependentSchemas
Not processed. Referenced schemas within are discovered for model generation, but conditional application is not enforced
Array
Field
Support
Behavior
prefixItems
Generates tuple[T1, T2, ...] for fixed-position arrays. With items: false produces a fixed-length tuple. With an items schema falls back to list[Union]
contains
Generates AfterValidator that validates at least one item matches the subschema. Supported patterns: const, enum, pattern, numeric range, string length. Complex subschemas not processed
minContains
Enforced via AfterValidator — counts matching items and raises ValueError when below the threshold (default 1)
maxContains
Enforced via AfterValidator — counts matching items and raises ValueError when above the threshold
Object
Field
Support
Behavior
propertyNames
Generates AfterValidator validating all dict keys. Supported: const, enum, pattern, minLength/maxLength. {"type": "string"} is a no-op
unevaluatedProperties
Composition-aware additionalProperties. false produces a strict model, true/schema produces a permissive model. Takes precedence over additionalProperties. Sub-schema validation on extras not enforced
unevaluatedItems
false with prefixItems produces a fixed-length tuple[T1, T2, ...]. Same effect as items: false at code generation level
patternProperties
Standalone usage maps to dict[str, T] with regex patterns in Field(json_schema_extra=...). When combined with properties, named fields are generated but regex-keyed extras are not surfaced as parameters
Schema Identity / Reference
Field
Support
Behavior
$id
Schemas with $id URIs are resolved to standard #/components/schemas/... references. Supports absolute URIs, relative URIs, and nested $id scope chains
$anchor
$ref: "#myAnchor" resolved to standard JSON Pointer references
$defs
Definitions are hoisted into components/schemas with collision-safe renaming. All $defs references rewritten to standard JSON Pointers
$dynamicRef
$dynamicRef: "#name" resolved by matching $dynamicAnchor: "name" within the same document. Full dynamic scoping not implemented
$dynamicAnchor
Same limitation as $dynamicRef — duplicate names use first-seen rather than dynamic scoping precedence
$vocabulary
Meta-schema keyword. Not applicable to code generation
Reusable Path Item Objects referenced via $ref from paths are fully resolved. Path-level parameters, sibling overrides, and multiple paths referencing the same pathItem all work correctly
