diff --git a/versions/3.0.4.md b/versions/3.0.4.md index f53404321b..84a75f14b4 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -8,7 +8,7 @@ This document is licensed under [The Apache License, Version 2.0](https://www.ap ## Introduction -The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. +The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. An OpenAPI description can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. @@ -81,7 +81,7 @@ This document serves as the [schema](#schema) for the OpenAPI Specification form This specification also _uses_ schemas in the form of the [Schema Object](#schemaObject). ##### 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. +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). @@ -142,7 +142,7 @@ For example, if a field has an array value, the JSON array representation will b ```json { - "field": [ 1, 2, 3 ] + "field": [1, 2, 3] } ``` All field names in the specification are **case sensitive**. @@ -218,12 +218,12 @@ Note that no aspect of implicit connection resolution changes how [URLs are reso ### Data Types -Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). +Data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#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. `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution). Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00. -Primitives have an optional modifier property: `format`. +Data types can have an optional modifier property: `format`. OAS uses several known 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. Formats such as `"email"`, `"uuid"`, and so on, MAY be used even though they are not defined by this specification. @@ -284,19 +284,19 @@ In the following description, if a field is not explicitly **REQUIRED** or descr #### OpenAPI Object -This is the root document object of the [OpenAPI document](#oasDocument). +This is the root object of the [OpenAPI document](#oasDocument). ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. +openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string. info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`. paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API. -components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. +components | [Components Object](#componentsObject) | An element to hold various schemas for the document. security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. 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. Individual operations can override this definition. To make security optional, an empty security requirement (`{}`) can be included in the array. -tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. +tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -311,8 +311,8 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi Field Name | Type | Description ---|:---:|--- title | `string` | **REQUIRED**. The title of the API. -description | `string` | A short description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. +description | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +termsOfService | `string` | A URL for the Terms of Service for the API. This MUST be in the form of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the version of the API being described). @@ -326,10 +326,10 @@ This object MAY be extended with [Specification Extensions](#specificationExtens { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", - "termsOfService": "http://example.com/terms/", + "termsOfService": "https://example.com/terms/", "contact": { "name": "API Support", - "url": "http://www.example.com/support", + "url": "https://www.example.com/support", "email": "support@example.com" }, "license": { @@ -343,10 +343,10 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```yaml title: Sample Pet Store App description: This is a sample server for a pet store. -termsOfService: http://example.com/terms/ +termsOfService: https://example.com/terms/ contact: name: API Support - url: http://www.example.com/support + url: https://www.example.com/support email: support@example.com license: name: Apache 2.0 @@ -363,8 +363,8 @@ Contact information for the exposed API. Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. -email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. +url | `string` | The URL for the contact information. This MUST be in the form of a URL. +email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -373,14 +373,14 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { "name": "API Support", - "url": "http://www.example.com/support", + "url": "https://www.example.com/support", "email": "support@example.com" } ``` ```yaml name: API Support -url: http://www.example.com/support +url: https://www.example.com/support email: support@example.com ``` @@ -393,7 +393,7 @@ License information for the exposed API. Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The license name used for the API. -url | `string` | A URL to the license used for the API. MUST be in the format of a URL. +url | `string` | A URL for the license used for the API. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -654,14 +654,14 @@ my.org.User "securitySchemes": { "api_key": { "type": "apiKey", - "name": "api_key", + "name": "api-key", "in": "header" }, "petstore_auth": { "type": "oauth2", "flows": { "implicit": { - "authorizationUrl": "http://example.org/api/oauth/dialog", + "authorizationUrl": "https://example.org/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" @@ -731,23 +731,22 @@ components: securitySchemes: api_key: type: apiKey - name: api_key + name: api-key in: header petstore_auth: type: oauth2 flows: implicit: - authorizationUrl: http://example.org/api/oauth/dialog + authorizationUrl: https://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ``` - #### Paths Object Holds the relative paths to the individual endpoints and their operations. -The path is appended to the URL from the [Server Object](#serverObject) in order to construct the full URL. The Paths MAY be empty, due to [ACL constraints](#securityFiltering). +The path is appended to the URL from the [Server Object](#serverObject) in order to construct the full URL. The Paths Object MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering). ##### Patterned Fields @@ -832,7 +831,7 @@ The path itself is still exposed to the documentation viewer but they will not k Field Name | Type | Description ---|:---:|--- -$ref | `string` | Allows for an external definition of this path item. The referenced structure MUST be in the format of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. +$ref | `string` | Allows for a referenced definition of this path item. The value MUST be in the form of a URL, and the referenced structure MUST be in the form of a [Path Item Object](#pathItemObject). In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relativeReferences). summary| `string` | An optional string summary, intended to apply to all operations in this path. description | `string` | An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. get | [Operation Object](#operationObject) | A definition of a GET operation on this path. @@ -947,7 +946,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. 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 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. +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 (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` SHALL be ignored by consumers. responses | [Responses Object](#responsesObject) | **REQUIRED**. 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`. @@ -1039,6 +1038,7 @@ requestBody: content: application/x-www-form-urlencoded: schema: + type: object properties: name: description: Updated name of the pet @@ -1074,8 +1074,8 @@ Allows referencing an external resource for extended documentation. Field Name | Type | Description ---|:---:|--- -description | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. -url | `string` | **REQUIRED**. The URL for the target documentation. Value MUST be in the format of a URL. +description | `string` | A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +url | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1159,8 +1159,7 @@ Field Name | Type | Description ---|:---:|--- content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry. - -##### Style Values +##### Style Values In order to support common ways of serializing simple parameters, a set of `style` values are defined. @@ -1195,7 +1194,7 @@ The following table shows examples, as would be shown with the `example` or `exa * Note that the `?` prefix is not appropriate for serializing `application/x-www-form-urlencoded` HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the [Encoding Object](#encodingObject) for more information * The examples are percent-encoded as required by RFC6570 and RFC3986; see [Appendix E](#percentEncodingAndFormMediaTypes) for a thorough discussion of percent-encoding concerns, including why unencoded `|` (`%7C`), `[` (`%5B`), and `]` (`%5D`) seem to work in some environments despite not being compliant. -[`style`](#dataTypeFormat) | `explode` | `empty` | `string` | `array` | `object` +[`style`](#styleValues) | `explode` | `empty` | `string` | `array` | `object` ----------- | ------ | -------- | -------- | -------- | ------- matrix | false | ;color | ;color=blue | ;color=blue,black,brown | ;color=R,100,G,200,B,150 matrix | true | ;color | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150 @@ -1397,7 +1396,7 @@ A request body with a referenced schema definition. "examples": { "user" : { "summary": "User Example", - "externalValue": "http://foo.bar/examples/user-example.json" + "externalValue": "https://foo.bar/examples/user-example.json" } } }, @@ -1408,7 +1407,7 @@ A request body with a referenced schema definition. "examples": { "user" : { "summary": "User example in XML", - "externalValue": "http://foo.bar/examples/user-example.xml" + "externalValue": "https://foo.bar/examples/user-example.xml" } } }, @@ -1416,7 +1415,7 @@ A request body with a referenced schema definition. "examples": { "user" : { "summary": "User example in Plain text", - "externalValue": "http://foo.bar/examples/user-example.txt" + "externalValue": "https://foo.bar/examples/user-example.txt" } } }, @@ -1424,7 +1423,7 @@ A request body with a referenced schema definition. "examples": { "user" : { "summary": "User example in other format", - "externalValue": "http://foo.bar/examples/user-example.whatever" + "externalValue": "https://foo.bar/examples/user-example.whatever" } } } @@ -1440,25 +1439,25 @@ content: $ref: '#/components/schemas/User' examples: user: - summary: User Example - externalValue: http://foo.bar/examples/user-example.json + summary: User example + externalValue: https://foo.bar/examples/user-example.json application/xml: schema: $ref: '#/components/schemas/User' examples: user: - summary: User Example in XML - externalValue: http://foo.bar/examples/user-example.xml + summary: User example in XML + externalValue: https://foo.bar/examples/user-example.xml text/plain: examples: user: - summary: User example in text plain format - externalValue: http://foo.bar/examples/user-example.txt + summary: User example in plain text + externalValue: https://foo.bar/examples/user-example.txt '*/*': examples: user: summary: User example in other format - externalValue: http://foo.bar/examples/user-example.whatever + externalValue: https://foo.bar/examples/user-example.whatever ``` #### Media Type Object @@ -1474,7 +1473,7 @@ Field Name | Type | Description schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the content of the request, response, parameter, or header. example | Any | Example of the media type; see [Working With Examples](#working-with-examples). examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type; see [Working With Examples](#working-with-examples). -encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and information providing more control over the serialization of the value. The key, being the property name, MUST exist in the schema as a property. The encoding attribute SHALL only apply to [Request Body Objects](#requestBodyObject), and only when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. +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 attribute SHALL only apply to [Request Body Objects](#requestBodyObject), and only when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1860,10 +1859,11 @@ The documentation is not necessarily expected to cover all possible HTTP respons However, documentation is expected to cover a successful operation response and any known errors. The `default` MAY be used as a default response object for all HTTP codes -that are not covered individually by the specification. +that are not covered individually by the Responses Object. -The Responses Object MUST contain at least one response code, and it -SHOULD be the response for a successful operation call. +The Responses Object MUST contain at least one response code, and if only one +response code is provided it SHOULD be the response for a successful operation +call. ##### Fixed Fields Field Name | Type | Description @@ -1929,7 +1929,7 @@ Describes a single response from an API Operation, including design-time, static ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -description | `string` | **REQUIRED**. A short description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | **REQUIRED**. A description of the response. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | Maps a header name to its definition. [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive. If a response header is defined with the name `"Content-Type"`, it SHALL be ignored. content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing descriptions of potential response payloads. The key is a media type or [media type range](https://tools.ietf.org/html/rfc7231#appendix-D) and the value describes it. For responses that match multiple keys, only the most specific key is applicable. e.g. text/plain overrides text/* links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for [Component Objects](#componentsObject). @@ -2082,36 +2082,36 @@ This includes accessing any part of a body that a JSON Pointer [RFC6901](https:/ For example, given the following HTTP request: ```http -POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1 +POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1 Host: example.org Content-Type: application/json Content-Length: 187 { - "failedUrl" : "http://clientdomain.com/failed", + "failedUrl" : "https://clientdomain.com/failed", "successUrls" : [ - "http://clientdomain.com/fast", - "http://clientdomain.com/medium", - "http://clientdomain.com/slow" + "https://clientdomain.com/fast", + "https://clientdomain.com/medium", + "https://clientdomain.com/slow" ] } 201 Created -Location: http://example.org/subscription/1 +Location: https://example.org/subscription/1 ``` The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named `eventType` and a query parameter named `queryUrl`. Expression | Value ---|:--- -$url | http://example.org/subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning +$url | https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning $method | POST $request.path.eventType | myevent -$request.query.queryUrl | http://clientdomain.com/stillrunning +$request.query.queryUrl | https://clientdomain.com/stillrunning $request.header.content-Type | application/json -$request.body#/failedUrl | http://clientdomain.com/failed -$request.body#/successUrls/1 | http://clientdomain.com/medium -$response.header.Location | http://example.org/subscription/1 +$request.body#/failedUrl | https://clientdomain.com/failed +$request.body#/successUrls/1 | https://clientdomain.com/medium +$response.header.Location | https://example.org/subscription/1 ##### Callback Object Examples @@ -2163,7 +2163,7 @@ Field Name | Type | Description summary | `string` | Short description for the example. description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary. -externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. +externalValue | `string` | A URL that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The `value` field and `externalValue` field are mutually exclusive. See the rules for resolving [Relative References](#relativeReferences). This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2215,7 +2215,7 @@ requestBody: examples: textExample: summary: This is a text example - externalValue: http://foo.bar/examples/address-example.txt + externalValue: https://foo.bar/examples/address-example.txt ``` In a parameter: @@ -2446,8 +2446,7 @@ links: ``` Note that in the use of `operationRef`, the _escaped forward-slash_ is necessary when -using JSON Pointers, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively when -using JSON Pointers as URI fragments. +using JSON Pointer, and it is necessary to URL-encode `{` and `}` as `%7B` and `%7D`, respectively when using JSON Pointer as URI fragments. ##### Runtime Expressions @@ -2476,7 +2475,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA ``` -Here, `json-pointer` is taken from [RFC 6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC 7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC 7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). +Here, `json-pointer` is taken from [RFC6901](https://tools.ietf.org/html/rfc6901), `char` from [RFC7159](https://tools.ietf.org/html/rfc7159#section-7) and `token` from [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2.6). The `name` identifier is case-sensitive, whereas `token` is not. @@ -2605,7 +2604,7 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED**. The name of the tag. -description | `string` | A short description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2627,7 +2626,7 @@ description: Pets operations #### Reference Object -A simple object to allow referencing other components in the specification, internally and externally. +A simple object to allow referencing other components in the OpenAPI document, internally and externally. The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. @@ -3158,7 +3157,7 @@ The expectation now is that a property with name `petType` _MUST_ be present in } ``` -Will indicate that the `Cat` schema be used in conjunction with this payload. +Will indicate that the `Cat` schema is expected to match this payload. 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: @@ -3178,7 +3177,7 @@ MyResponseType: Here the discriminating value of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`. If the discriminating value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. -When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. +When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity for serializers/deserializers where multiple schemas may satisfy a single payload. This example shows the `allOf` usage, which avoids needing to reference all child schemas in the parent: @@ -3222,7 +3221,7 @@ components: type: boolean ``` -a payload like this: +Validated against the `Pet` schema, a payload like this: ```json { @@ -3231,7 +3230,7 @@ a payload like this: } ``` -will indicate that the `Cat` schema be used. Likewise this schema: +will indicate that the `#/components/schemas/Cat` schema is expected to match. Likewise this payload: ```json { @@ -3240,7 +3239,7 @@ will indicate that the `Cat` schema be used. Likewise this schema: } ``` -will map to `Dog` because of the definition in the `mappings` element. +will map to `#/components/schemas/Dog` because the `dog` entry in the `mapping` element maps to `Dog` which is the schema name for `#/components/schemas/Dog`. #### XML Object @@ -3363,7 +3362,7 @@ In this example, a full model definition is shown. "name": { "type": "string", "xml": { - "namespace": "http://example.com/schema/sample", + "namespace": "https://example.com/schema/sample", "prefix": "sample" } } @@ -3384,13 +3383,13 @@ Person: name: type: string xml: - namespace: http://example.com/schema/sample + namespace: https://example.com/schema/sample prefix: sample ``` ```xml - example + example ``` @@ -3612,7 +3611,7 @@ Supported schemes are HTTP authentication, an API key (either as a header, a coo Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. -description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. +description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used. in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`. scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml). The value is case-insensitive, as defined in [RFC7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1). @@ -3643,14 +3642,14 @@ scheme: basic ```json { "type": "apiKey", - "name": "api_key", + "name": "api-key", "in": "header" } ``` ```yaml type: apiKey -name: api_key +name: api-key in: header ``` @@ -3660,7 +3659,7 @@ in: header { "type": "http", "scheme": "bearer", - "bearerFormat": "JWT", + "bearerFormat": "JWT" } ``` @@ -3718,9 +3717,9 @@ Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. +authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -3961,7 +3960,7 @@ While not part of the specification itself, certain libraries MAY choose to allo Two examples of this: -1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication. +1. The [Paths Object](#pathsObject) MAY be present but empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They would still have access to at least the [Info Object](#infoObject) which may contain additional information regarding authentication. 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see. ## Security Considerations @@ -4031,7 +4030,7 @@ To control the serialization of numbers, booleans, and `null` (or other values R The resulting strings would not require any further type conversion. The `format` keyword can assist in serialization. -Some formats (such as `date-time` or `byte`) are unambiguous, while others (such as [`decimal`](https://spec.openapis.org/registry/format/decimal.html) in the [Format Registry](https://spec.openapis.org/registry/format/)) are less clear. +Some formats (such as `date-time`) are unambiguous, while others (such as [`decimal`](https://spec.openapis.org/registry/format/decimal.html) in the [Format Registry](https://spec.openapis.org/registry/format/)) are less clear. However, care must be taken with `format` to ensure that the specific formats are supported by all relevant tools as unrecognized formats are ignored. Requiring input as pre-formatted, schema-validated strings also improves round-trip interoperability as not all programming languages and environments support the same data types.