Skip to main content
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)

FieldSupportBehavior
openapi"3.2.x" accepted
$selfDocument’s canonical URI. Appears as “Specification Source” in generated server docstring

​
Server Object

FieldSupportBehavior
nameServer host identifier. Appears as “Server” in generated server docstring

​
Path Item Object

FieldSupportBehavior
queryHTTP 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)
additionalOperationsMap 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

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

StyleSupportBehavior
cookieRFC 6265-compliant cookie serialization. Name-value pairs separated by ; , no percent-encoding. Supports primitives, arrays, and objects with explode control

​
Changed Field Types

FieldSupportBehavior
contentMap values now allow Reference Objects. $ref values in content maps are resolved transparently

​
Request Body Object

FieldSupportBehavior
contentMap values now accept Reference Objects. $ref values resolved transparently

​
Media Type Object

FieldSupportBehavior
itemSchemaSchema for each item in sequential media types. Planned for future streaming support
prefixEncodingPositional Encoding Objects for multipart types. Planned for future streaming support
itemEncodingPer-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 TypeSupportBehavior
application/jsonlJSON Lines — each line is a JSON value
application/x-ndjsonNewline-Delimited JSON
application/json-seqJSON Text Sequences (RFC 7464)
text/event-streamServer-Sent Events (SSE)
multipart/mixedSequential multipart content

​
Responses

​
Response Object

FieldSupportBehavior
descriptionAbsent descriptions handled gracefully
contentMap 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.
CategoryFormatsSupport
Integerint8, int16, int32, int64, uint8, uint16, uint32, uint64, double-int
Numberfloat, double, decimal, decimal128
Binary/encodingbyte, binary, base64url
Date/timedate, date-time, time, duration, date-time-local, time-local, http-date, unixtime
String/textpassword, commonmark, html, char, regex
Email/hostnameemail, idn-email, hostname, idn-hostname
Network/identifiersipv4, 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

FieldSupportBehavior
propertyNameThe discriminating property MAY now be optional. When optional, defaultMapping must be present
defaultMappingFallback schema when the discriminating property is absent or unmapped

​
Components Object

FieldSupportBehavior
pathItemsReusable Path Item Objects via $ref from paths
mediaTypesReusable Media Type Objects via $ref from content maps

​
Security Scheme Object

FieldSupportBehavior
deprecatedSupported on Operations and Parameters. Not yet supported on Security Schemes
oauth2MetadataUrlOAuth 2.0 Authorization Server Metadata URL (RFC 8414)

​
OAuth Flows Object

FieldSupportBehavior
deviceAuthorizationOAuth 2.0 Device Authorization Grant (RFC 8628). Generated server handles device code flow with user instructions and token polling

​
OAuth Flow Object

FieldSupportBehavior
deviceAuthorizationUrlRequired for deviceAuthorization flow. Used as the device authorization endpoint

​
Security Requirement Object

FeatureSupportBehavior
URI-based referencesCross-document security scheme references via URIs. Planned for multi-file specification support

​
Example Object

FieldSupportBehavior
valueDeprecated in 3.2 in favor of dataValue. Still fully functional
dataValueStructured example data. Mutually exclusive with value
serializedValueWire-format string of the example. JSON strings are deserialized and used; non-JSON formats not processed

​
Tag Object

FieldSupportBehavior
parentResolved to hierarchical paths (e.g., tag refunds with parent: payments becomes payments/refunds). Parent chains of any depth with cycle detection
kindClassification string (e.g., nav, lifecycle, badge). Rendered alongside tags in tool comments as tag (kind)
summaryNot processed

​
Encoding Object

FieldSupportBehavior
encodingNested Encoding Objects for multipart content
prefixEncodingPositional encoding for multipart
itemEncodingPer-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.