diff --git a/README.md b/README.md index fec337e71a..e8f9f8e39b 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ This GitHub project is the starting point for OpenAPI. Here you will find the in The current version of the OpenAPI specification is [OpenAPI Specification 3.0.3](versions/3.0.3.md). -## Current Release Candidate Version - 3.1.0-RC0 +## Current Release Candidate Version - 3.1.0-RC1 -We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC0](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev). +We invite the community to review and provide feedback for the current release candidate ([OpenAPI Specification 3.1.0-RC1](versions/3.1.0.md). Changes related to the upcoming 3.1.0 release should be submitted at [the development branch](https://github.com/OAI/OpenAPI-Specification/tree/v3.1.0-dev). ### Previous Versions diff --git a/versions/3.1.0.md b/versions/3.1.0.md index fc282f3777..16fd23689e 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -1,6 +1,6 @@ # OpenAPI Specification -#### Version 3.1.0-rc0 +#### Version 3.1.0-rc1 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. @@ -73,7 +73,7 @@ A self-contained or composite resource which defines or describes an API or elem ##### Path Templating Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters. -Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). +Each template expression in the path MUST correspond to a path parameter that is included in the [Path Item](#path-item-object) itself and/or in each of the Path Item's [Operations](#operation-object). An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required. ##### Media Types Media type definitions are spread across several resources. @@ -139,17 +139,12 @@ It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `op ### Data Types -Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.2). +Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2019-09](http://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.4.2). Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2019-09. -Primitives have an optional modifier property: `format`, which is defined by JSON Schema. -OAS uses several known additional formats to define in fine detail the data type being used. -However, to support documentation needs, the `format` property is an open `string`-valued property, and can have any value. -Additional formats MAY be used even though undefined by either JSON Schema or this specification. -Types that are not accompanied by a `format` property follow the type definition in the JSON Schema. Tools that do not recognize a specific `format` MAY default back to the `type` alone, as if the `format` is not specified. - -Note that by default, JSON Schema validators will not attempt to validate the `format` keyword. https://json-schema.org/draft/2019-09/release-notes.html#format-vocabulary +As defined by JSON Schema, data types can have an optional modifier property: `format`. +OAS defines additional formats to provide fine detail for primitive data types. The formats defined by the OAS are: @@ -429,8 +424,8 @@ An object representing a Server Variable for server URL template substitution. Field Name | Type | Description ---|:---:|--- -enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array SHOULD NOT be empty. -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. If the [`enum`](#serverVariableEnum) is defined, the value SHOULD exist in the enum's values. +enum | [`string`] | An enumeration of string values to be used if the substitution options are from a limited set. The array MUST NOT be empty. +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. If the [`enum`](#serverVariableEnum) is defined, the value MUST exist in the enum's values. description | `string` | An optional description for the server variable. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -445,7 +440,7 @@ All objects defined within the components object will have no effect on the API Field Name | Type | Description ---|:---|--- - schemas | Map[`string`, [Schema Object](#schemaObject) | An object to hold reusable [Schema Objects](#schemaObject). + schemas | Map[`string`, [Schema Object](#schemaObject)] | An object to hold reusable [Schema Objects](#schemaObject). responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject). @@ -850,7 +845,7 @@ Field Name | Type | Description 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. 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). requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation. The `requestBody` is fully 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 (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible. -responses | [Responses Object](#responsesObject) | **REQUIRED**. The list of possible responses as they are returned from executing this operation. +responses | [Responses Object](#responsesObject) | The list of possible responses as they are returned from executing this operation. callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a [Callback Object](#callbackObject) that describes a request that may be initiated by the API provider and the expected responses. deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement (`{}`) can be included in the array. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. @@ -1485,7 +1480,7 @@ In addition, specific media types MAY be specified: # multiple, specific media types may be specified: requestBody: content: - # a binary file of type png or jpeg + # a binary file of type png or jpeg image/jpeg: {} image/png: {} ``` @@ -2336,6 +2331,14 @@ As such, inline schema definitions, which do not have a given id, *cannot* be us The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. The [XML Object](#xmlObject) contains additional information about the available options. +###### Picking Schema Vocabularies + +It is important for tooling to be able to detect what meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema Object, or some custom meta schema. + +`$schema` MAY be present in any Schema Object, and if present MUST be used to determine which dialect should be used when processing the schema. + +When `$schema` is not present, the default the following dialect MUST be assumed: `$schema: "https://spec.openapis.org/oas/3.1/schema-object"`. + ##### Schema Object Examples ###### Primitive Sample @@ -3419,6 +3422,7 @@ Two examples of this: Version | Date | Notes --- | --- | --- +3.1.0-rc0 | 2020-10-08 | rc1 of the 3.1 specification 3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification 3.0.3 | 2020-02-20 | Patch release of the OpenAPI Specification 3.0.3 3.0.2 | 2018-10-08 | Patch release of the OpenAPI Specification 3.0.2