Skip to content

Instantly share code, notes, and snippets.

@podhmo
Created December 9, 2023 08:24
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save podhmo/2951aca2112f77ef2d77740bab4e4daf to your computer and use it in GitHub Desktop.
Save podhmo/2951aca2112f77ef2d77740bab4e4daf to your computer and use it in GitHub Desktop.
--- 3.0.1.md 2023-12-09 17:21:54
+++ 3.0.2.md 2023-12-09 17:21:54
@@ -1,6 +1,6 @@
# OpenAPI Specification
-#### Version 3.0.1
+#### Version 3.0.2
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
@@ -118,6 +118,7 @@
}
```
All field names in the specification are **case sensitive**.
+This includes all fields that are used as keys in a map, except where explicitly noted that keys are **case insensitive**.
The schema exposes two types of fields: Fixed fields, which have a declared name, and Patterned fields, which declare a regex pattern for the field name.
@@ -151,19 +152,20 @@
The formats defined by the OAS are:
-Common Name | [`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
------------ | ------ | -------- | --------
-integer | `integer` | `int32` | signed 32 bits
-long | `integer` | `int64` | signed 64 bits
-float | `number` | `float` | |
-double | `number` | `double` | |
-string | `string` | | |
-byte | `string` | `byte` | base64 encoded characters
-binary | `string` | `binary` | any sequence of octets
-boolean | `boolean` | | |
-date | `string` | `date` | As defined by `full-date` - [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
-dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
-password | `string` | `password` | A hint to UIs to obscure input.
+[`type`](#dataTypes) | [`format`](#dataTypeFormat) | Comments
+------ | -------- | --------
+`integer` | `int32` | signed 32 bits
+`integer` | `int64` | signed 64 bits (a.k.a long)
+`number` | `float` | |
+`number` | `double` | |
+`string` | | |
+`string` | `byte` | base64 encoded characters
+`string` | `binary` | any sequence of octets
+`boolean` | | |
+`string` | `date` | As defined by `full-date` - [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
+`string` | `date-time` | As defined by `date-time` - [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
+`string` | `password` | A hint to UIs to obscure input.
+
### <a name="richText"></a>Rich Text Formatting
Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
@@ -218,7 +220,7 @@
This object MAY be extended with [Specification Extensions](#specificationExtensions).
-##### Info Object Example:
+##### Info Object Example
```json
{
@@ -266,7 +268,7 @@
This object MAY be extended with [Specification Extensions](#specificationExtensions).
-##### Contact Object Example:
+##### Contact Object Example
```json
{
@@ -295,7 +297,7 @@
This object MAY be extended with [Specification Extensions](#specificationExtensions).
-##### License Object Example:
+##### License Object Example
```json
{
@@ -428,7 +430,7 @@
Field Name | Type | Description
---|:---:|---
<a name="serverVariableEnum"></a>enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set.
-<a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value to use for substitution, and to send, if an alternate value is _not_ supplied. Unlike the [Schema Object's](#schemaObject) `default`, this value MUST be provided by the consumer.
+<a name="serverVariableDefault"></a>default | `string` | **REQUIRED**. The default value to use for substitution, which SHALL be sent if an alternate value is _not_ supplied. Note this behavior is different than the [Schema Object's](#schemaObject) treatment of default values, because in those cases parameter values are optional.
<a name="serverVariableDescription"></a>description | `string` | An optional description for the server variable. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -472,6 +474,18 @@
```json
"components": {
"schemas": {
+ "GeneralError": {
+ "type": "object",
+ "properties": {
+ "code": {
+ "type": "integer",
+ "format": "int32"
+ },
+ "message": {
+ "type": "string"
+ }
+ }
+ },
"Category": {
"type": "object",
"properties": {
@@ -562,6 +576,14 @@
```yaml
components:
schemas:
+ GeneralError:
+ type: object
+ properties:
+ code:
+ type: integer
+ format: int32
+ message:
+ type: string
Category:
type: object
properties:
@@ -823,7 +845,7 @@
<a name="operationSummary"></a>summary | `string` | A short summary of what the operation does.
<a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
-<a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
+<a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions.
<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's components/parameters](#componentsParameters).
<a name="operationRequestBody"></a>requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
<a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation.
@@ -883,7 +905,7 @@
}
},
"405": {
- "description": "Invalid input",
+ "description": "Method Not Allowed",
"content": {
"application/json": {},
"application/xml": {}
@@ -933,7 +955,7 @@
'application/json': {}
'application/xml': {}
'405':
- description: Invalid input
+ description: Method Not Allowed
content:
'application/json': {}
'application/xml': {}
@@ -992,8 +1014,8 @@
<a name="parameterIn"></a>in | `string` | **REQUIRED**. The location of the parameter. Possible values are "query", "header", "path" or "cookie".
<a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameterIn) is "path", this property is **REQUIRED** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`.
-<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.
-<a name="parameterAllowEmptyValue"></a> allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored.
+<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
+<a name="parameterAllowEmptyValue"></a> allowEmptyValue | `boolean` | Sets the ability to pass empty-valued parameters. This is valid only for `query` parameters and allows sending a parameter with an empty value. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Use of this property is NOT RECOMMENDED, as it is likely to be removed in a later revision.
The rules for serialization of the parameter are specified in one of two ways.
For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter.
@@ -1342,7 +1364,7 @@
##### Fixed Fields
Field Name | Type | Description
---|:---:|---
-<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body.
+<a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the content of the request, response, or parameter.
<a name="mediaTypeExample"></a>example | Any | Example of the media type. The example object SHOULD be in the correct format as specified by the media type. The `example` field is mutually exclusive of the `examples` field. Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.
<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type. Each example object SHOULD match the media type and specified schema if present. The `examples` field is mutually exclusive of the `example` field. Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
<a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.
@@ -1351,7 +1373,7 @@
##### Media Type Examples
-```js
+```json
{
"application/json": {
"schema": {
@@ -1626,7 +1648,7 @@
##### Patterned Fields
Field Pattern | Type | Description
---|:---:|---
-<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. The following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response range is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
+<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) \| [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A [Reference Object](#referenceObject) can link to a response that is defined in the [OpenAPI Object's components/responses](#componentsResponses) section. This field MUST be enclosed in quotation marks (for example, "200") for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character `X`. For example, `2XX` represents all response codes between `[200-299]`. Only the following range definitions are allowed: `1XX`, `2XX`, `3XX`, `4XX`, and `5XX`. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -1862,7 +1884,7 @@
$request.path.eventType | myevent
$request.query.queryUrl | http://clientdomain.com/stillrunning
$request.header.content-Type | application/json
-$request.body#/failedUrl | http://clientdomain.com/stillrunning
+$request.body#/failedUrl | http://clientdomain.com/failed
$request.body#/successUrls/2 | http://clientdomain.com/medium
$response.header.Location | http://example.org/subscription/1
@@ -1903,10 +1925,11 @@
of its associated value. Tooling implementations MAY choose to
validate compatibility automatically, and reject the example value(s) if incompatible.
-##### Example Object Example
+##### Example Object Examples
+In a model:
+
```yaml
-# in a model
schemas:
properties:
name:
@@ -1914,54 +1937,62 @@
examples:
name:
$ref: http://example.org/petapi-examples/openapi.json#/components/examples/name-example
+```
-# in a request body:
- requestBody:
- content:
- 'application/json':
- schema:
- $ref: '#/components/schemas/Address'
- examples:
- foo:
- summary: A foo example
- value: {"foo": "bar"}
- bar:
- summary: A bar example
- value: {"bar": "baz"}
- 'application/xml':
- examples:
- xmlExample:
- summary: This is an example in XML
- externalValue: 'http://example.org/examples/address-example.xml'
- 'text/plain':
- examples:
- textExample:
- summary: This is a text example
- externalValue: 'http://foo.bar/examples/address-example.txt'
+In a request body:
-
-# in a parameter
- parameters:
- - name: 'zipCode'
- in: 'query'
- schema:
- type: 'string'
- format: 'zip-code'
- examples:
- zip-example:
- $ref: '#/components/examples/zip-example'
+```yaml
+requestBody:
+ content:
+ 'application/json':
+ schema:
+ $ref: '#/components/schemas/Address'
+ examples:
+ foo:
+ summary: A foo example
+ value: {"foo": "bar"}
+ bar:
+ summary: A bar example
+ value: {"bar": "baz"}
+ 'application/xml':
+ examples:
+ xmlExample:
+ summary: This is an example in XML
+ externalValue: 'http://example.org/examples/address-example.xml'
+ 'text/plain':
+ examples:
+ textExample:
+ summary: This is a text example
+ externalValue: 'http://foo.bar/examples/address-example.txt'
+```
-# in a response
- responses:
- '200':
- description: your car appointment has been booked
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/SuccessResponse'
- examples:
- confirmation-success:
- $ref: '#/components/examples/confirmation-success'
+In a parameter:
+
+```yaml
+parameters:
+ - name: 'zipCode'
+ in: 'query'
+ schema:
+ type: 'string'
+ format: 'zip-code'
+ examples:
+ zip-example:
+ $ref: '#/components/examples/zip-example'
+```
+
+In a response:
+
+```yaml
+responses:
+ '200':
+ description: your car appointment has been booked
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/SuccessResponse'
+ examples:
+ confirmation-success:
+ $ref: '#/components/examples/confirmation-success'
```
@@ -2271,7 +2302,7 @@
- not - Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
- items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. `items` MUST be present if the `type` is `array`.
- properties - Property definitions MUST be a [Schema Object](#schemaObject) and not a standard JSON Schema (inline or referenced).
-- additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema.
+- additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a [Schema Object](#schemaObject) and not a standard JSON Schema. Consistent with JSON Schema, `additionalProperties` defaults to `true`.
- description - [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
- format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the OAS offers a few additional predefined formats.
- default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
@@ -2655,11 +2686,11 @@
<a name="propertyName"></a>propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value.
<a name="discriminatorMapping"></a> mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references.
-The discriminator attribute is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.
+The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`.
In OAS 3.0, a response payload MAY be described to be exactly one of any number of types:
-```
+```yaml
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
@@ -2670,22 +2701,22 @@
which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use:
-```
+```yaml
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
- $ref: '#/components/schemas/Lizard'
discriminator:
- propertyName: pet_type
+ propertyName: petType
```
-The expectation now is that a property with name `pet_type` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload:
+The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload:
-```
+```json
{
"id": 12345,
- "pet_type": "Cat"
+ "petType": "Cat"
}
```
@@ -2693,7 +2724,7 @@
In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used:
-```
+```yaml
MyResponseType:
oneOf:
- $ref: '#/components/schemas/Cat'
@@ -2701,7 +2732,7 @@
- $ref: '#/components/schemas/Lizard'
- $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
discriminator:
- propertyName: pet_type
+ propertyName: petType
mapping:
dog: '#/components/schemas/Dog'
monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
@@ -2715,20 +2746,20 @@
For example:
-```
+```yaml
components:
schemas:
Pet:
type: object
required:
- - pet_type
+ - petType
properties:
- pet_type:
+ petType:
type: string
discriminator:
- propertyName: pet_type
+ propertyName: petType
mapping:
- cachorro: Dog
+ dog: Dog
Cat:
allOf:
- $ref: '#/components/schemas/Pet'
@@ -2757,18 +2788,18 @@
a payload like this:
-```
+```json
{
- "pet_type": "Cat",
+ "petType": "Cat",
"name": "misty"
}
```
will indicate that the `Cat` schema be used. Likewise this schema:
-```
+```json
{
- "pet_type": "cachorro",
+ "petType": "dog",
"bark": "soft"
}
```
@@ -3132,7 +3163,7 @@
#### <a name="securitySchemeObject"></a>Security Scheme Object
Defines a security scheme that can be used by the operations.
-Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
+Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06).
##### Fixed Fields
Field Name | Type | Applies To | Description
@@ -3276,7 +3307,7 @@
}
```
-```YAML
+```yaml
type: oauth2
flows:
implicit:
@@ -3301,7 +3332,7 @@
Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized.
This enables support for scenarios where multiple query parameters or HTTP headers are required to convey security information.
-When a list of Security Requirement Objects is defined on the [Open API object](#oasObject) or [Operation Object](#operationObject), only one of Security Requirement Objects in the list needs to be satisfied to authorize the request.
+When a list of Security Requirement Objects is defined on the [OpenAPI Object](#oasObject) or [Operation Object](#operationObject), only one of the Security Requirement Objects in the list needs to be satisfied to authorize the request.
##### Patterned Fields
@@ -3368,6 +3399,7 @@
Version | Date | Notes
--- | --- | ---
+3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2
3.0.1 | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1
3.0.0 | 2017-07-26 | Release of the OpenAPI Specification 3.0.0
3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment