OpenAPI 3.1

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.

Data Types

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`
`type: "null"` standalone		Maps to `None` type annotation
`contentSchema`		Schema of decoded content. Not processed

OpenAPI Object (Root)

Field	Support	Behavior
`paths`		Specification must contain at least one of `paths`, `components`, or `webhooks`. Specifications without `paths` produce no tools
`jsonSchemaDialect`		Standard OAS 3.1 dialect assumed. Custom JSON Schema dialects not supported
`webhooks`		Not supported. Planned for a future release

Info Object

New summary field added to the Info Object.

Field	Support	Behavior
`summary`		Rendered in generated server module docstring and README

License Object

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

Schema Object

The Schema Object is now a superset of JSON Schema Draft 2020-12.

Changed Keywords

Field	Support	Behavior
`exclusiveMaximum`		Now a standalone number (was boolean in 3.0). Both forms generate correct `Field(lt=...)` constraints
`exclusiveMinimum`		Now a standalone number (was boolean in 3.0). Both forms generate correct `Field(gt=...)` constraints
`type`		Can now be a string or array. `["string", "null"]` maps to `str \| None`, `["string", "integer"]` maps to `str \| int`
`example`		Deprecated in 3.1 in favor of `examples`. Both forms are read and emitted in generated `Field(examples=[...])`
`$ref` siblings		`$ref` can now coexist with sibling keywords. Generated output merges `description`, `summary`, `default`, `deprecated`, `readOnly`, `writeOnly` from siblings
`nullable`		Removed in 3.1, replaced by type arrays. Both forms produce identical `T \| None` type annotation. See nullable limitation

New JSON Schema 2020-12 Keywords

Conditional / Composition

Field	Support	Behavior
`if` / `then` / `else`		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
`$comment`		Human-readable comment. No runtime effect
`$schema`		Per-schema dialect declaration

Content

Field	Support	Behavior
`contentEncoding`		See Data Types section
`contentMediaType`		See Data Types section
`contentSchema`		Not processed

Metadata

Field	Support	Behavior
`examples` (array)		Emitted in generated `Field(examples=[...])` alongside the deprecated `example` keyword

Components Object

Field	Support	Behavior
`pathItems`		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

Reference Object

New summary and description sibling properties.

Field	Support	Behavior
`summary`		Overrides referenced component’s summary in generated output
`description`		Overrides referenced component’s description in generated output

In OAS 3.0, $ref siblings were supposed to be ignored. The generator already supported summary/description siblings, now officially sanctioned by 3.1.

Security Scheme Object

New mutualTLS type.

Field	Support	Behavior
`mutualTLS` type		TLS transport layer authentication via client certificates. Generated server configures mTLS cert/key paths via environment variables

Found an issue?

Generated server doesn’t match this reference? Let us know — we’ll fix it.

Getting Started

Generator

Your Generated Server

Deployment

Reference

Data Types

OpenAPI Object (Root)

Info Object

License Object

Schema Object

Changed Keywords

New JSON Schema 2020-12 Keywords

Conditional / Composition

Array

Object

Schema Identity / Reference

Content

Metadata

Components Object

Reference Object

Security Scheme Object

Found an issue?

​Data Types

​OpenAPI Object (Root)

​Info Object

​License Object

​Schema Object

​Changed Keywords

​New JSON Schema 2020-12 Keywords

Conditional / Composition

Array

Object

Schema Identity / Reference

Content

Metadata

​Components Object

​Reference Object

​Security Scheme Object

Found an issue?

Data Types

OpenAPI Object (Root)

Info Object

License Object

Schema Object

Changed Keywords

New JSON Schema 2020-12 Keywords

Components Object

Reference Object

Security Scheme Object