1.
Introduction to
OpenAPI 3.1
Darrel Miller
Ron Ratovsky
OAI Technical Steering Committee Members

2.
Proprietary & Confidential
3
OpenAPI 3.1

3.
Proprietary & Confidential
4
OpenAPI
2.0
2014
2015
2016
2017
OpenAPI
3.0
OpenAPI
3.0.2
2018
2019
Alternative
Schema
Pilot
OpenAPI
3.1
2021
Overlays
OpenAPI Specification History

4.
Proprietary & Confidential
5
OpenAPI Versioning
3.0
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0
(semver) and follows the semver specification.
3.0.3
Each new minor version of the OpenAPI Specification SHALL allow any
OpenAPI document that is valid against any previous minor version of the
Specification, within the same major version, to be updated to the new
Specification version with equivalent semantics. Such an update MUST
only require changing the openapi property to the new minor version.
3.1
Occasionally, non-backwards compatible changes may be made in minor
versions of the OAS where impact is believed to be low relative to the
benefit provided.
Yay SemVer!
Clarity!
Err SemVer?
Need more
precision!
Boo SemVer!

5.
Proprietary & Confidential
6
Info Object
https://spdx.org/licenses/
openapi: 3.1.0
info:
title: My Demo API
version: 1.0.0
summary: An API with examples of features in 3.1
license:
name: Apache 2.0
identifier: Apache-2.0 SPDX Identifier for machine
processing

6.
Proprietary & Confidential
7
Webhooks
openapi: 3.1.0
info:
title: My Demo API
version: 1.0.0
summary: An API with examples of features in 3.1
webhooks:
newThingAlert:
$ref: '#/components/pathItems/newThingAlert'
components:
pathItems:
newThingAlert:
summary: Notification that a new thing has been created
post:
requestBody:
content:
applicaton/json:
schema:
type: object
properties:
thingName:
type: string
Reusable Path Items
Out-of-band registered
callbacks

7.
Proprietary & Confidential
8
paths:
/todos:
post:
requestBody:
content:
application/json:
schema:
summary: A new todo object
description: |
This is where where a new todo
object can be described.
$ref: "#/components/schemas/todo“
responses:
201:
description: Created
components:
schemas:
todo:
title: A todo object
type: object
properties:
id:
type: integer
description:
type: string
$ref
SHOULD
override
Correction: The ability to override values
is only within the Reference Object and
cannot be used inside the Schema Object

8.
Proprietary & Confidential
9
openapi: 3.1.0
info:
title: Security Demo
version: 1.0.0
paths:
/todos:
post:
...
security:
clientCertificate:
- todo.write
components:
securitySchemes:
clientCertificate:
type: mutualTLS
Security
Roles/Claims for non-OAuth
schemes
New security scheme type for client
certificates

9.
Proprietary & Confidential
10
OpenAPI Documents
paths
webhooks
components

10.
Proprietary & Confidential
11
Odds and Ends Allowed request body for all HTTP methods
Added multipart/form-data support for encoding
object
Path Item parameters must be defined
Removed definition of some formats e.g. byte,
binary
Responses are now optional

11.
Proprietary & Confidential
12
OpenAPI & JSON Schema
OpenAPI 3.0
OpenAPI
Schema
OpenAPI Tools JSON Schema Tools
OpenAPI 3.1
JSON Schema
Draft 2020-09
OpenAPI Tools JSON Schema Tools
Partially
Broken
OpenAPI
Schema Tools

12.
Proprietary & Confidential
13
Full JSON Schema Support
- Full type support (nullable is gone)
- Formats are… not enforced
- exclusiveMinimum/Maximum, readOnly/writeOnly
- file uploads, contentEncoding, contentMediaType
- $schema and dialects (jsonSchemaDialect)
- $id

13.
Proprietary & Confidential
14
Relative References
URIs
(relative to document)
• Reference Object
• Path Item Object
• $ref
• Link Object
• operationRef
URLs
(relative to servers)
• External Documentation
• License
• Security URLs

14.
Proprietary & Confidential
15
The Future
Overlays: Separate document that augments another API description
Reusable groups: $ref more than one component
Alternative Schemas
Optional and Multi-segment Paths
Disambiguating based on query
Digital Signatures and Encryption
Discovery mechanism for security credentials (jwt, apikey, etc)