What’s new in OpenAPI 3.2

What’s new in OpenAPI 3.2 Lorna Mitchell, TM Forum

OpenAPI 3.2: September 2025 OpenAPI 3.1: February 2021 OpenAPI 3.0: July 2017 https://lornajane.net OpenAPI 3.2

QUERY is supported alongside GET, POST New field additionalOperations for all everything else. HTTP methods paths: /cakes: query: summary: Advanced cake search requestBody: # … complex search criteria responses: ‘200’: # … search results additionalOperations: LINK: summary: Link related products requestBody: # … link relationship data https://lornajane.net

New parameter location: querystring. /cakes/search?flavour=pink&tags=mini querystring /cakes/search: get: parameters: - name: search in: querystring content: application/x-www-form-urlencoded: schema: type: object properties: flavour: type: string inStock: type: boolean tags: type: array items: type: string https://lornajane.net

Responses may contain repeating schemas described by itemSchema. Sequential media types Media types registry published to showcase using the different features. Supported formats include: • text/event_stream • application/jsonl • application/json-seq • multipart/mixed https://lornajane.net

New fields to go with multipart/mixed support: itemSchema to describe the structure of a Multipart media types repeating payload. itemEncoding to describe the encoding for a collection of items. prefixEncoding to describe encoding by position where the multipart is a series of entries in a known order. https://lornajane.net

$self sets the base URI of the document. Used in reference resolution. $self keyword openapi: 3.2.0 $self: https://example.com/my-api/openapi.yaml info: title: Example API components: schemas: Foo: properties: bar: $ref: schemas/bar.json Resolves to https://example.com/my-api/ schemas/bar.json https://lornajane.net

Upgrades to example value fields: Examples • dataValue to describe the structure • serializedValue to show how it will be transmitted No change to value or externalValue. https://lornajane.net

Security schemes can be marked deprecated. New OAuth2 flow: Device Authorization. Security New field for OAuth2 Metadata oauth2metadataurl. https://lornajane.net

New field nodeType to indicate what type of node a schema represents. XML upgrades Values: element (default), attribute, text, cdata, none. Upgrade from attribute: true to nodeType: attribute. https://lornajane.net

Field in propertyName can be an optional field. defaultMapping provides a default Discriminator schema to use if no match exists. schemas: Cake: type: object discriminator: propertyName: cakeType defaultMapping: sponge mapping: sponge: ‘#/components/schemas/SpongeCake’ chocolate: ‘#/components/schemas/ChocolateCake’ fruit: ‘#/components/schemas/FruitCake’ properties: cakeType: type: string https://lornajane.net

summary for a human-readable short name. kind to allow multiple categories of tag (not just documentation). A registry for tag kinds is published. parent supports nesting. https://lornajane.net Tags reimagined

• name: prod summary: Products description: All products kind: nav - name: cake summary: Cakes description: Custom cakes and layer cakes parent: prod kind: nav - name: bread summary: Breads description: Artisan breads and rolls parent: prod kind: nav - name: seasonal summary: Seasonal description: Limited-time seasonal offerings kind: badge externalDocs: description: Seasonal menu planning url: https://docs.bakery.com/seasonal https://lornajane.net Tags reimagined

Support by modern tooling Improved developer experience, discriminator, querystring Improved user experience, tags and examples New HTTP methods, new security flows More media types supported for a wider range of applications https://lornajane.net OpenAPI upgrades

Keep reading … https://spec.openapis.org https://learn.openapis.org Resources https://lornajane.net https://tmforum.org https://apisyouwonthate.com https://openapi.tools https://lornajane.net

Open standard Membership Events OpenAPI and you Working groups • Arazzo • Overlays • Industry standards • Moonwalk (OpenAPI 4.0) • Outreach https://lornajane.net