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