Skip to content

Commit a75318f

Browse files
fehguyfehguy
committed
Merge branch 'OpenAPI.next' into issue-589
2 parents 5e97498 + c5f620d commit a75318f

File tree

1 file changed

+30
-80
lines changed

1 file changed

+30
-80
lines changed

‎versions/3.0.md

Lines changed: 30 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -134,11 +134,7 @@ Field Name | Type | Description
134134
<a name="oasTags"></a>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.
135135
<a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
136136

137-
##### Patterned Objects
138-
139-
Field Pattern | Type | Description
140-
---|:---:|---
141-
<a name="oasExtensions"></a>^x- | Any | Allows extensions to the OAS Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
137+
This object can be extended with [Specification Extensions](#specificationExtensions).
142138

143139
#### <a name="oasVersion"></a>OpenAPI Version String
144140

@@ -165,11 +161,7 @@ Field Name | Type | Description
165161
<a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
166162
<a name="infoVersion"></a>version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version).
167163

168-
##### Patterned Objects
169-
170-
Field Pattern | Type | Description
171-
---|:---:|---
172-
<a name="infoExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
164+
This object can be extended with [Specification Extensions](#specificationExtensions).
173165

174166
##### Info Object Example:
175167

@@ -229,11 +221,7 @@ Field Name | Type | Description
229221
<a name="contactUrl"></a>url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
230222
<a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
231223

232-
##### Patterned Objects
233-
234-
Field Pattern | Type | Description
235-
---|:---:|---
236-
<a name="contactExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
224+
This object can be extended with [Specification Extensions](#specificationExtensions).
237225

238226
##### Contact Object Example:
239227

@@ -262,11 +250,7 @@ Field Name | Type | Description
262250
<a name="licenseName"></a>name | `string` | **Required.** The license name used for the API.
263251
<a name="licenseUrl"></a>url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
264252

265-
##### Patterned Objects
266-
267-
Field Pattern | Type | Description
268-
---|:---:|---
269-
<a name="licenseExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
253+
This object can be extended with [Specification Extensions](#specificationExtensions).
270254

271255
##### License Object Example:
272256

@@ -309,7 +293,8 @@ The Paths may be empty, due to [ACL constraints](#securityFiltering).
309293
Field Pattern | Type | Description
310294
---|:---:|---
311295
<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is appended to the [`basePath`](#oasBasePath) in order to construct the full URL. [Path templating](#pathTemplating) is allowed.
312-
<a name="pathsExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
296+
297+
This object can be extended with [Specification Extensions](#specificationExtensions).
313298

314299
##### Paths Object Example
315300

@@ -378,11 +363,8 @@ Field Name | Type | Description
378363
<a name="pathItemSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
379364
<a name="pathItemParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. 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 parameters](#oasParameters).
380365

381-
##### Patterned Fields
382366

383-
Field Pattern | Type | Description
384-
---|:---:|---
385-
<a name="pathItemExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
367+
This object can be extended with [Specification Extensions](#specificationExtensions).
386368

387369
##### Path Item Object Example
388370

@@ -489,11 +471,7 @@ Field Name | Type | Description
489471
<a name="operationBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#pathItemHost). This optional value will override the top-level [basePath](#oasBasePath) or path item-level [basePath](#oasPathItemBasePath) if present. If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating).
490472
<a name="operationSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) or path-item level [schemes](#pathItemSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
491473

492-
##### Patterned Objects
493-
494-
Field Pattern | Type | Description
495-
---|:---:|---
496-
<a name="operationExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
474+
This object can be extended with [Specification Extensions](#specificationExtensions).
497475

498476
##### Operation Object Example
499477

@@ -613,11 +591,7 @@ Field Name | Type | Description
613591
<a name="externalDocDescription"></a>description | `string` | A short description of the target documentation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
614592
<a name="externalDocUrl"></a>url | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL.
615593

616-
##### Patterned Objects
617-
618-
Field Pattern | Type | Description
619-
---|:---:|---
620-
<a name="externalDocExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
594+
This object can be extended with [Specification Extensions](#specificationExtensions).
621595

622596
##### External Documentation Object Example
623597

@@ -658,12 +632,7 @@ Field Name | Type | Description
658632
<a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
659633
<a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the parameter.
660634

661-
662-
##### Patterned Fields
663-
Field Pattern | Type | Description
664-
---|:---:|---
665-
<a name="parameterExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
666-
635+
This object can be extended with [Specification Extensions](#specificationExtensions).
667636

668637
##### Parameter Object Examples
669638

@@ -1011,11 +980,7 @@ Field Name | Type | Description
1011980
<a name="itemsEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
1012981
<a name="itemsMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
1013982

1014-
##### Patterned Objects
1015-
1016-
Field Pattern | Type | Description
1017-
---|:---:|---
1018-
<a name="itemsExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
983+
This object can be extended with [Specification Extensions](#specificationExtensions).
1019984

1020985
##### Items Object Examples
1021986

@@ -1076,9 +1041,10 @@ It can be used to cover undeclared responses.
10761041
Field Pattern | Type | Description
10771042
---|:---:|---
10781043
<a name="responsesCode"></a>[HTTP Status Code](#httpCodes) | [Response Object](#responseObject) <span>&#124;</span> [Reference Object](#referenceObject) | Any [HTTP status code](#httpCodes) can be used as the property name (one property per HTTP status code). Describes the expected response for that HTTP status code. [Reference Object](#referenceObject) can be used to link to a response that is defined at the [OpenAPI Object's responses](#oasResponses) section. This field must quoted for compatibility between JSON and YAML (i.e. "200"), and may contain the uppercase character, `X` to designate a wildcard, such as `2XX` to represent all response codes between `[200-299]`.
1079-
<a name="responsesExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
10801044

10811045

1046+
This object can be extended with [Specification Extensions](#specificationExtensions).
1047+
10821048
##### Responses Object Example
10831049

10841050
A 200 response for successful operation and a default response for others (implying an error):
@@ -1140,10 +1106,11 @@ Field Name | Type | Description
11401106
Field Pattern | Type | Description
11411107
---|:---:|---
11421108
<a name="representations"></a>`*` | [Schema Object](#schemaObject)<span>&#124;</span> [Reference Object](#referenceObject) | A schema describing the response value for a specific `Content-Type`
1143-
<a name="responseExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
11441109

11451110
Representations may take the form of a wildcard (`*`) to designate any `Content-Type`, or a regular expression for matching a specific type
11461111

1112+
This object can be extended with [Specification Extensions](#specificationExtensions).
1113+
11471114
##### Response Object Examples
11481115

11491116
Response of an array of a complex type:
@@ -1266,7 +1233,8 @@ A container for possible out-of band callbacks from an operation. A callback may
12661233
Field Pattern | Type | Description
12671234
---|:---:|---
12681235
<a name="responseName"></a>Callback name | [Callback Operation Object](#operationObject) <span>&#124;</span> [Operation Object](#operationObject) | An operation object used to define a callback payload structure
1269-
<a name="responsesExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
1236+
1237+
This object can be extended with [Specification Extensions](#specificationExtensions).
12701238

12711239

12721240
##### Callback Object Example
@@ -1391,7 +1359,8 @@ operationId | string | the name of an _existing_, resolvable OAS operation, as d
13911359
parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
13921360
headers | Link Headers Object | an Object representing headers to pass to the linked resource.
13931361
description | string | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
1394-
^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
1362+
1363+
This object can be extended with [Specification Extensions](#specificationExtensions).
13951364

13961365
Locating a linked resource may be performed by either a `href` or `operationId`.
13971366
In the case of an `operationId`, it must be unique and resolved in the scope of the OAS document.
@@ -1802,11 +1771,7 @@ Field Name | Type | Description
18021771
<a name="headerEnum"></a>enum | [*] | See http://json-schema.org/latest/json-schema-validation.html#anchor76.
18031772
<a name="headerMultipleOf"></a>multipleOf | `number` | See http://json-schema.org/latest/json-schema-validation.html#anchor14.
18041773

1805-
##### Patterned Objects
1806-
1807-
Field Pattern | Type | Description
1808-
---|:---:|---
1809-
<a name="headerExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
1774+
This object can be extended with [Specification Extensions](#specificationExtensions).
18101775

18111776
##### Header Object Example
18121777

@@ -1836,10 +1801,7 @@ Field Name | Type | Description
18361801
<a name="tagDescription"></a>description | `string` | A short description for the tag. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
18371802
<a name="tagExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag.
18381803

1839-
##### Patterned Fields
1840-
Field Pattern | Type | Description
1841-
---|:---:|---
1842-
<a name="tagExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
1804+
This object can be extended with [Specification Extensions](#specificationExtensions).
18431805

18441806
##### Tag Object Example
18451807

@@ -2013,11 +1975,7 @@ Field Name | Type | Description
20131975
<a name="schemaExamples"></a>examples | Any | An array of free-formed properties to include examples for this schema.
20141976
<a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and should be transitioned out of usage.
20151977

2016-
##### Patterned Objects
2017-
2018-
Field Pattern | Type | Description
2019-
---|:---:|---
2020-
<a name="schemaExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
1978+
This object can be extended with [Specification Extensions](#specificationExtensions).
20211979

20221980
###### Composition and Inheritance (Polymorphism)
20231981

@@ -2419,11 +2377,7 @@ Field Name | Type | Description
24192377
<a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`.
24202378
<a name="xmlWrapped"></a>wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `<books><book/><book/></books>`) or unwrapped (`<book/><book/>`). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`).
24212379

2422-
##### Patterned Objects
2423-
2424-
Field Pattern | Type | Description
2425-
---|:---:|---
2426-
<a name="xmlExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
2380+
This object can be extended with [Specification Extensions](#specificationExtensions).
24272381

24282382
##### XML Object Examples
24292383

@@ -2992,11 +2946,7 @@ Field Name | Type | Validity | Description
29922946
<a name="securitySchemeTokenUrl"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"application"`, `"accessCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL.
29932947
<a name="securitySchemeScopes"></a>scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme.
29942948

2995-
##### Patterned Fields
2996-
2997-
Field Name | Type | Description
2998-
---|:---:|---
2999-
<a name="securitySchemeExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
2949+
This object can be extended with [Specification Extensions](#specificationExtensions).
30002950

30012951
##### Security Scheme Object Example
30022952

@@ -3061,11 +3011,7 @@ Field Pattern | Type | Description
30613011
---|:---:|---
30623012
<a name="scopesName"></a>{name} | `string` | Maps between a name of a scope to a short description of it (as the value of the property).
30633013

3064-
##### Patterned Objects
3065-
3066-
Field Pattern | Type | Description
3067-
---|:---:|---
3068-
<a name="scopesExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Specification Extensions](#specificationExtensions) for further details.
3014+
This object can be extended with [Specification Extensions](#specificationExtensions).
30693015

30703016
##### Scopes Object Example
30713017

@@ -3129,7 +3075,11 @@ petstore_auth:
31293075

31303076
While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.
31313077

3132-
The extensions properties are always prefixed by `"x-"` and can have any valid JSON format value.
3078+
The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
3079+
3080+
Field Pattern | Type | Description
3081+
---|:---:|---
3082+
<a name="infoExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. Can have any valid JSON format value.
31333083

31343084
The extensions may or may not be supported by the available tooling, but those may be extended as well to add requested support (if tools are internal or open-sourced).
31353085

0 commit comments

Comments
 (0)