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
Newsummary field added to the Info Object.| Field | Support | Behavior |
|---|---|---|
summary | Rendered in generated server module docstring and README |
License Object
Newidentifier 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
Newsummary 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
NewmutualTLS 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.