OpenAPI 3.2

This page covers new and changed features in OpenAPI 3.2 relative to OAS 3.1. Only deltas are documented — for base feature coverage, see the OAS 3.0 and OAS 3.1 pages.

OpenAPI Object (Root)

Field	Support	Behavior
`openapi`		`"3.2.x"` accepted
`$self`		Document’s canonical URI. Appears as “Specification Source” in generated server docstring

Server Object

Field	Support	Behavior
`name`		Server host identifier. Appears as “Server” in generated server docstring

Path Item Object

Field	Support	Behavior
`query`		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`		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`		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`		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`		Map values now allow Reference Objects. `$ref` values in `content` maps are resolved transparently

Request Body Object

Field	Support	Behavior
`content`		Map values now accept Reference Objects. `$ref` values resolved transparently

Media Type Object

Field	Support	Behavior
`itemSchema`		Schema for each item in sequential media types. Planned for future streaming support
`prefixEncoding`		Positional Encoding Objects for multipart types. Planned for future streaming support
`itemEncoding`		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`		JSON Lines — each line is a JSON value
`application/x-ndjson`		Newline-Delimited JSON
`application/json-seq`		JSON Text Sequences (RFC 7464)
`text/event-stream`		Server-Sent Events (SSE)
`multipart/mixed`		Sequential multipart content

Responses

Response Object

Field	Support	Behavior
`description`		Absent descriptions handled gracefully
`content`		Map values now accept Reference Objects. `$ref` values resolved transparently

OAS Format Registry

OAS 3.2 introduced the OAS Format Registry — 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		`int8`, `int16`, `int32`, `int64`, `uint8`, `uint16`, `uint32`, `uint64`, `double-int`
Number		`float`, `double`, `decimal`, `decimal128`
Binary/encoding		`byte`, `binary`, `base64url`
Date/time		`date`, `date-time`, `time`, `duration`, `date-time-local`, `time-local`, `http-date`, `unixtime`
String/text		`password`, `commonmark`, `html`, `char`, `regex`
Email/hostname		`email`, `idn-email`, `hostname`, `idn-hostname`
Network/identifiers		`ipv4`, `ipv6`, `uri`, `uri-reference`, `uri-template`, `iri`, `iri-reference`, `uuid`, `json-pointer`, `relative-json-pointer`, `media-range`
Structured Fields (RFC 8941)		`sf-integer`, `sf-decimal`, `sf-string`, `sf-token`, `sf-boolean`, `sf-binary`

For detailed behavior of each format, see the Extended Formats table on the OAS 3.0 page. MCP Blacksmith also supports custom formats not in the registry for common API conventions.

Schema Object

No changes from 3.1. See OAS 3.1 Schema Object for full coverage.

Discriminator Object

Field	Support	Behavior
`propertyName`		The discriminating property MAY now be optional. When optional, `defaultMapping` must be present
`defaultMapping`		Fallback schema when the discriminating property is absent or unmapped

Components Object

Field	Support	Behavior
`pathItems`		Reusable Path Item Objects via `$ref` from `paths`
`mediaTypes`		Reusable Media Type Objects via `$ref` from `content` maps

Security Scheme Object

Field	Support	Behavior
`deprecated`		Supported on Operations and Parameters. Not yet supported on Security Schemes
`oauth2MetadataUrl`		OAuth 2.0 Authorization Server Metadata URL (RFC 8414)

OAuth Flows Object

Field	Support	Behavior
`deviceAuthorization`		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`		Required for `deviceAuthorization` flow. Used as the device authorization endpoint

Security Requirement Object

Feature	Support	Behavior
URI-based references		Cross-document security scheme references via URIs. Planned for multi-file specification support

Example Object

Field	Support	Behavior
`value`		Deprecated in 3.2 in favor of `dataValue`. Still fully functional
`dataValue`		Structured example data. Mutually exclusive with `value`
`serializedValue`		Wire-format string of the example. JSON strings are deserialized and used; non-JSON formats not processed

Tag Object

Field	Support	Behavior
`parent`		Resolved to hierarchical paths (e.g., tag `refunds` with `parent: payments` becomes `payments/refunds`). Parent chains of any depth with cycle detection
`kind`		Classification string (e.g., `nav`, `lifecycle`, `badge`). Rendered alongside tags in tool comments as `tag (kind)`
`summary`		Not processed

Encoding Object

Field	Support	Behavior
`encoding`		Nested Encoding Objects for multipart content
`prefixEncoding`		Positional encoding for multipart
`itemEncoding`		Per-item encoding for multipart arrays

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.

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

OpenAPI Object (Root)

Server Object

Path Item Object

Parameter Object

New Parameter Location

New Serialization Style

Changed Field Types

Request Body Object

Media Type Object

Sequential Media Types

Responses

Response Object

OAS Format Registry

Schema Object

Discriminator Object

Components Object

Security Scheme Object

OAuth Flows Object

OAuth Flow Object

Security Requirement Object

Example Object

Tag Object

Encoding Object

Found an issue?

​OpenAPI Object (Root)

​Server Object

​Path Item Object

​Parameter Object

​New Parameter Location

​New Serialization Style

​Changed Field Types

​Request Body Object

​Media Type Object

​Sequential Media Types

​Responses

​Response Object

​OAS Format Registry

​Schema Object

​Discriminator Object

​Components Object

​Security Scheme Object

​OAuth Flows Object

​OAuth Flow Object

​Security Requirement Object

​Example Object

​Tag Object

​Encoding Object

Found an issue?

OpenAPI Object (Root)

Server Object

Path Item Object

Parameter Object

New Parameter Location

New Serialization Style

Changed Field Types

Request Body Object

Media Type Object

Sequential Media Types

Responses

Response Object

OAS Format Registry

Schema Object

Discriminator Object

Components Object

Security Scheme Object

OAuth Flows Object

OAuth Flow Object

Security Requirement Object

Example Object

Tag Object

Encoding Object