> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcpblacksmith.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAPI 3.1

> Compliance reference for new and changed features in OpenAPI 3.1 (JSON Schema 2020-12 alignment).

This page covers new and changed features in [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.1.md) (3.1.0–3.1.2) relative to [OAS 3.0](/reference/oas-3-0). Only deltas are documented — for base feature coverage, see the [OAS 3.0](/reference/oas-3-0) page.

<div className="oas-compliance-table">
  ### Data Types

  OAS 3.1 aligns data types with JSON Schema Draft 2020-12. The primitive format table is unchanged from [OAS 3.0](/reference/oas-3-0#data-types).

  | Field                     | Support                                                          | Behavior                                                                                                                                                                |
  | ------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `type` as array           | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `["string", "null"]` maps to `str \| None`, `["string", "integer"]` maps to `str \| int`                                                                                |
  | `contentEncoding`         | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `base64`/`base64url` generates `format: byte` validation. `base16`/`base32` stored as metadata. Raw value surfaced in `Field(json_schema_extra=...)` for LLM visibility |
  | `contentMediaType`        | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Surfaced in `Field(json_schema_extra=...)` alongside `contentEncoding` and `format`                                                                                     |
  | `type: "null"` standalone | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Maps to `None` type annotation                                                                                                                                          |
  | `contentSchema`           | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Schema of decoded content. Not processed                                                                                                                                |

  ### OpenAPI Object (Root)

  | Field               | Support                                                          | Behavior                                                                                                                         |
  | ------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
  | `paths`             | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Specification must contain at least one of `paths`, `components`, or `webhooks`. Specifications without `paths` produce no tools |
  | `jsonSchemaDialect` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Standard OAS 3.1 dialect assumed. Custom JSON Schema dialects not supported                                                      |
  | `webhooks`          | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Not supported. Planned for a future release                                                                                      |

  ### Info Object

  New `summary` field added to the Info Object.

  | Field     | Support                                                          | Behavior                                                 |
  | --------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
  | `summary` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Rendered in generated server module docstring and README |

  #### License Object

  New `identifier` field for SPDX license expressions.

  | Field        | Support                                                          | Behavior                                                                                                                                                                   |
  | ------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `identifier` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | 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` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Now a standalone number (was boolean in 3.0). Both forms generate correct `Field(lt=...)` constraints                                                                   |
  | `exclusiveMinimum` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Now a standalone number (was boolean in 3.0). Both forms generate correct `Field(gt=...)` constraints                                                                   |
  | `type`             | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Can now be a string or array. `["string", "null"]` maps to `str \| None`, `["string", "integer"]` maps to `str \| int`                                                  |
  | `example`          | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Deprecated in 3.1 in favor of `examples`. Both forms are read and emitted in generated `Field(examples=[...])`                                                          |
  | `$ref` siblings    | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | `$ref` can now coexist with sibling keywords. Generated output merges `description`, `summary`, `default`, `deprecated`, `readOnly`, `writeOnly` from siblings          |
  | `nullable`         | <Icon icon="triangle-exclamation" iconType="solid" color="#eab308" size={18} /> | Removed in 3.1, replaced by type arrays. Both forms produce identical `T \| None` type annotation. See [nullable limitation](/reference/oas-3-0#oas-extension-keywords) |

  #### New JSON Schema 2020-12 Keywords

  ##### Conditional / Composition

  | Field                  | Support                                                          | Behavior                                                                                                                          |
  | ---------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
  | `if` / `then` / `else` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Generates `@model_validator` with conditional logic. When `if` matches, `then` constraints enforced; otherwise `else` constraints |
  | `dependentRequired`    | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Generates `@model_validator` enforcing "if field X present, fields Y and Z required"                                              |
  | `const`                | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Generates `Literal[value]` type annotation                                                                                        |
  | `dependentSchemas`     | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Not processed. Referenced schemas within are discovered for model generation, but conditional application is not enforced         |

  ##### Array

  | Field         | Support                                                          | Behavior                                                                                                                                                                                          |
  | ------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `prefixItems` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | 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`    | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | 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` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Enforced via `AfterValidator` — counts matching items and raises `ValueError` when below the threshold (default 1)                                                                                |
  | `maxContains` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Enforced via `AfterValidator` — counts matching items and raises `ValueError` when above the threshold                                                                                            |

  ##### Object

  | Field                   | Support                                                                         | Behavior                                                                                                                                                                                                         |
  | ----------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `propertyNames`         | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Generates `AfterValidator` validating all dict keys. Supported: `const`, `enum`, `pattern`, `minLength`/`maxLength`. `{"type": "string"}` is a no-op                                                             |
  | `unevaluatedProperties` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | 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`      | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | `false` with `prefixItems` produces a fixed-length `tuple[T1, T2, ...]`. Same effect as `items: false` at code generation level                                                                                  |
  | `patternProperties`     | <Icon icon="triangle-exclamation" iconType="solid" color="#eab308" size={18} /> | 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`            | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Schemas with `$id` URIs are resolved to standard `#/components/schemas/...` references. Supports absolute URIs, relative URIs, and nested `$id` scope chains |
  | `$anchor`        | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | `$ref: "#myAnchor"` resolved to standard JSON Pointer references                                                                                             |
  | `$defs`          | <Icon icon="check" iconType="solid" color="#16a34a" size={20} />                | Definitions are hoisted into `components/schemas` with collision-safe renaming. All `$defs` references rewritten to standard JSON Pointers                   |
  | `$dynamicRef`    | <Icon icon="triangle-exclamation" iconType="solid" color="#eab308" size={18} /> | `$dynamicRef: "#name"` resolved by matching `$dynamicAnchor: "name"` within the same document. Full dynamic scoping not implemented                          |
  | `$dynamicAnchor` | <Icon icon="triangle-exclamation" iconType="solid" color="#eab308" size={18} /> | Same limitation as `$dynamicRef` — duplicate names use first-seen rather than dynamic scoping precedence                                                     |
  | `$vocabulary`    | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} />                | Meta-schema keyword. Not applicable to code generation                                                                                                       |
  | `$comment`       | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} />                | Human-readable comment. No runtime effect                                                                                                                    |
  | `$schema`        | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} />                | Per-schema dialect declaration                                                                                                                               |

  ##### Content

  | Field              | Support                                                          | Behavior                              |
  | ------------------ | ---------------------------------------------------------------- | ------------------------------------- |
  | `contentEncoding`  | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | See [Data Types](#data-types) section |
  | `contentMediaType` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | See [Data Types](#data-types) section |
  | `contentSchema`    | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Not processed                         |

  ##### Metadata

  | Field              | Support                                                          | Behavior                                                                                |
  | ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
  | `examples` (array) | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Emitted in generated `Field(examples=[...])` alongside the deprecated `example` keyword |

  ### Components Object

  | Field       | Support                                                          | Behavior                                                                                                                                                                                          |
  | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `pathItems` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | 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`     | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Overrides referenced component's summary in generated output     |
  | `description` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Overrides referenced component's description in generated output |

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

  ### Security Scheme Object

  New `mutualTLS` type.

  | Field            | Support                                                          | Behavior                                                                                                                              |
  | ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
  | `mutualTLS` type | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | TLS transport layer authentication via client certificates. Generated server configures mTLS cert/key paths via environment variables |

  <Card title="Found an issue?" icon="bug" href="https://mcpblacksmith.com/contact">
    Generated server doesn't match this reference? Let us know — we'll fix it.
  </Card>
</div>