> ## 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.2

> Compliance reference for new and changed features in OpenAPI Specification 3.2.

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

<div className="oas-compliance-table">
  ### OpenAPI Object (Root)

  | Field | Support | Behavior |
  | - | - | - |
  | `openapi` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `"3.2.x"` accepted |
  | `$self` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Document's canonical URI. Appears as "Specification Source" in generated server docstring |

  ### Server Object

  | Field | Support | Behavior |
  | - | - | - |
  | `name` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Server host identifier. Appears as "Server" in generated server docstring |

  ### Path Item Object

  | Field | Support | Behavior |
  | - | - | - |
  | `query` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | HTTP QUERY method. Generates an MCP tool identical to other HTTP methods. When `operationId` is absent, auto-generated name uses `query_` prefix (e.g., `query_search`) |
  | `additionalOperations` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Map of arbitrary HTTP method strings (e.g., COPY, MOVE, LOCK, PROPFIND) to Operation Objects. Each entry generates an MCP tool with the method string sent as-is (uppercased) |

  ### Parameter Object

  #### New Parameter Location

  | Location | Support | Behavior |
  | - | - | - |
  | `querystring` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Entire URL query string as a single parameter value, specified via `content` with a media type. Supported: `application/x-www-form-urlencoded`, `application/json` / `*+json`, `text/plain` / `text/*`. Unsupported media types fall back to `application/x-www-form-urlencoded` |

  #### New Serialization Style

  | Style | Support | Behavior |
  | - | - | - |
  | `cookie` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | RFC 6265-compliant cookie serialization. Name-value pairs separated by `; `, no percent-encoding. Supports primitives, arrays, and objects with explode control |

  #### Changed Field Types

  | Field | Support | Behavior |
  | - | - | - |
  | `content` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Map values now allow Reference Objects. `$ref` values in `content` maps are resolved transparently |

  ### Request Body Object

  | Field | Support | Behavior |
  | - | - | - |
  | `content` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Map values now accept Reference Objects. `$ref` values resolved transparently |

  ### Media Type Object

  | Field | Support | Behavior |
  | - | - | - |
  | `itemSchema` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Schema for each item in sequential media types. Planned for future streaming support |
  | `prefixEncoding` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Positional Encoding Objects for multipart types. Planned for future streaming support |
  | `itemEncoding` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Per-item Encoding Object for multipart arrays. Planned for future streaming support |

  #### Sequential Media Types

  OAS 3.2 formalizes sequential/streaming media types. Planned for future streaming support.

  | Media Type | Support | Behavior |
  | - | - | - |
  | `application/jsonl` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | JSON Lines — each line is a JSON value |
  | `application/x-ndjson` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Newline-Delimited JSON |
  | `application/json-seq` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | JSON Text Sequences (RFC 7464) |
  | `text/event-stream` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Server-Sent Events (SSE) |
  | `multipart/mixed` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Sequential multipart content |

  ### Responses

  #### Response Object

  | Field | Support | Behavior |
  | - | - | - |
  | `description` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Absent descriptions handled gracefully |
  | `content` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Map values now accept Reference Objects. `$ref` values resolved transparently |

  ### OAS Format Registry

  OAS 3.2 introduced the [OAS Format Registry](https://spec.openapis.org/registry/format/) — a canonical list of 49 format values for use with the `format` keyword. MCP Blacksmith supports all 49 registry formats with runtime validators.

  | Category | Support | Formats |
  | - | - | - |
  | Integer | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, `uint32`, `uint64`, `double-int` |
  | Number | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `float`, `double`, `decimal`, `decimal128` |
  | Binary/encoding | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `byte`, `binary`, `base64url` |
  | Date/time | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `date`, `date-time`, `time`, `duration`, `date-time-local`, `time-local`, `http-date`, `unixtime` |
  | String/text | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `password`, `commonmark`, `html`, `char`, `regex` |
  | Email/hostname | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `email`, `idn-email`, `hostname`, `idn-hostname` |
  | Network/identifiers | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `ipv4`, `ipv6`, `uri`, `uri-reference`, `uri-template`, `iri`, `iri-reference`, `uuid`, `json-pointer`, `relative-json-pointer`, `media-range` |
  | Structured Fields (RFC 8941) | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | `sf-integer`, `sf-decimal`, `sf-string`, `sf-token`, `sf-boolean`, `sf-binary` |

  For detailed behavior of each format, see the [Extended Formats](/reference/oas-3-0#extended-formats) table on the OAS 3.0 page. MCP Blacksmith also supports [custom formats](/reference/oas-3-0#custom-formats-not-in-oas-registry) not in the registry for common API conventions.

  ### Schema Object

  <Note>
    No changes from 3.1. See [OAS 3.1 Schema Object](/reference/oas-3-1#schema-object) for full coverage.
  </Note>

  #### Discriminator Object

  | Field | Support | Behavior |
  | - | - | - |
  | `propertyName` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | The discriminating property MAY now be optional. When optional, `defaultMapping` must be present |
  | `defaultMapping` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Fallback schema when the discriminating property is absent or unmapped |

  ### Components Object

  | Field | Support | Behavior |
  | - | - | - |
  | `pathItems` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Reusable Path Item Objects via `$ref` from `paths` |
  | `mediaTypes` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Reusable Media Type Objects via `$ref` from `content` maps |

  ### Security Scheme Object

  | Field | Support | Behavior |
  | - | - | - |
  | `deprecated` | <Icon icon="triangle-exclamation" iconType="solid" color="#eab308" size={18} /> | Supported on Operations and Parameters. Not yet supported on Security Schemes |
  | `oauth2MetadataUrl` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | OAuth 2.0 Authorization Server Metadata URL (RFC 8414) |

  #### OAuth Flows Object

  | Field | Support | Behavior |
  | - | - | - |
  | `deviceAuthorization` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | OAuth 2.0 Device Authorization Grant (RFC 8628). Generated server handles device code flow with user instructions and token polling |

  #### OAuth Flow Object

  | Field | Support | Behavior |
  | - | - | - |
  | `deviceAuthorizationUrl` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Required for `deviceAuthorization` flow. Used as the device authorization endpoint |

  #### Security Requirement Object

  | Feature | Support | Behavior |
  | - | - | - |
  | URI-based references | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Cross-document security scheme references via URIs. Planned for multi-file specification support |

  ### Example Object

  | Field | Support | Behavior |
  | - | - | - |
  | `value` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Deprecated in 3.2 in favor of `dataValue`. Still fully functional |
  | `dataValue` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Structured example data. Mutually exclusive with `value` |
  | `serializedValue` | <Icon icon="triangle-exclamation" iconType="solid" color="#eab308" size={18} /> | Wire-format string of the example. JSON strings are deserialized and used; non-JSON formats not processed |

  ### Tag Object

  | Field | Support | Behavior |
  | - | - | - |
  | `parent` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Resolved to hierarchical paths (e.g., tag `refunds` with `parent: payments` becomes `payments/refunds`). Parent chains of any depth with cycle detection |
  | `kind` | <Icon icon="check" iconType="solid" color="#16a34a" size={20} /> | Classification string (e.g., `nav`, `lifecycle`, `badge`). Rendered alongside tags in tool comments as `tag (kind)` |
  | `summary` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Not processed |

  ### Encoding Object

  | Field | Support | Behavior |
  | - | - | - |
  | `encoding` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Nested Encoding Objects for multipart content |
  | `prefixEncoding` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Positional encoding for multipart |
  | `itemEncoding` | <Icon icon="xmark" iconType="solid" color="#dc2626" size={20} /> | Per-item encoding for multipart arrays |

  <Note>
    The Encoding Object is not supported. Generated servers send form and multipart bodies using standard encoding — per-property overrides (`contentType`, `headers`, `style`) are rarely needed in practice.
  </Note>

  <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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.