Skip to content

Commit c5f620d

Browse files
fehguyfehguy
authored
Merge pull request #805 from OAI/dm/specification-extensions
Reorganized the Specification Extension references
2 parents 7562b8a + 0cb6708 commit c5f620d

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="infoObject"></a>Info Object
144140

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

159-
##### Patterned Objects
160-
161-
Field Pattern | Type | Description
162-
---|:---:|---
163-
<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.
155+
This object can be extended with [Specification Extensions](#specificationExtensions).
164156

165157
##### Info Object Example:
166158

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

223-
##### Patterned Objects
224-
225-
Field Pattern | Type | Description
226-
---|:---:|---
227-
<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.
215+
This object can be extended with [Specification Extensions](#specificationExtensions).
228216

229217
##### Contact Object Example:
230218

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

256-
##### Patterned Objects
257-
258-
Field Pattern | Type | Description
259-
---|:---:|---
260-
<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.
244+
This object can be extended with [Specification Extensions](#specificationExtensions).
261245

262246
##### License Object Example:
263247

@@ -300,7 +284,8 @@ The Paths may be empty, due to [ACL constraints](#securityFiltering).
300284
Field Pattern | Type | Description
301285
---|:---:|---
302286
<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.
303-
<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.
287+
288+
This object can be extended with [Specification Extensions](#specificationExtensions).
304289

305290
##### Paths Object Example
306291

@@ -369,11 +354,8 @@ Field Name | Type | Description
369354
<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.
370355
<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).
371356

372-
##### Patterned Fields
373357

374-
Field Pattern | Type | Description
375-
---|:---:|---
376-
<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.
358+
This object can be extended with [Specification Extensions](#specificationExtensions).
377359

378360
##### Path Item Object Example
379361

@@ -480,11 +462,7 @@ Field Name | Type | Description
480462
<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).
481463
<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.
482464

483-
##### Patterned Objects
484-
485-
Field Pattern | Type | Description
486-
---|:---:|---
487-
<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.
465+
This object can be extended with [Specification Extensions](#specificationExtensions).
488466

489467
##### Operation Object Example
490468

@@ -604,11 +582,7 @@ Field Name | Type | Description
604582
<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.
605583
<a name="externalDocUrl"></a>url | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL.
606584

607-
##### Patterned Objects
608-
609-
Field Pattern | Type | Description
610-
---|:---:|---
611-
<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.
585+
This object can be extended with [Specification Extensions](#specificationExtensions).
612586

613587
##### External Documentation Object Example
614588

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

652-
653-
##### Patterned Fields
654-
Field Pattern | Type | Description
655-
---|:---:|---
656-
<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.
657-
626+
This object can be extended with [Specification Extensions](#specificationExtensions).
658627

659628
##### Parameter Object Examples
660629

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

1005-
##### Patterned Objects
1006-
1007-
Field Pattern | Type | Description
1008-
---|:---:|---
1009-
<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.
974+
This object can be extended with [Specification Extensions](#specificationExtensions).
1010975

1011976
##### Items Object Examples
1012977

@@ -1067,9 +1032,10 @@ It can be used to cover undeclared responses.
10671032
Field Pattern | Type | Description
10681033
---|:---:|---
10691034
<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]`.
1070-
<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.
10711035

10721036

1037+
This object can be extended with [Specification Extensions](#specificationExtensions).
1038+
10731039
##### Responses Object Example
10741040

10751041
A 200 response for successful operation and a default response for others (implying an error):
@@ -1131,10 +1097,11 @@ Field Name | Type | Description
11311097
Field Pattern | Type | Description
11321098
---|:---:|---
11331099
<a name="representations"></a>`*` | [Schema Object](#schemaObject)<span>&#124;</span> [Reference Object](#referenceObject) | A schema describing the response value for a specific `Content-Type`
1134-
<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.
11351100

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

1103+
This object can be extended with [Specification Extensions](#specificationExtensions).
1104+
11381105
##### Response Object Examples
11391106

11401107
Response of an array of a complex type:
@@ -1257,7 +1224,8 @@ A container for possible out-of band callbacks from an operation. A callback may
12571224
Field Pattern | Type | Description
12581225
---|:---:|---
12591226
<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
1260-
<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.
1227+
1228+
This object can be extended with [Specification Extensions](#specificationExtensions).
12611229

12621230

12631231
##### Callback Object Example
@@ -1382,7 +1350,8 @@ operationId | string | the name of an _existing_, resolvable OAS operation, as d
13821350
parameters | Link Parameters Object | an Object representing parameters to pass to an operation as specified with `operationId` or identified via `href`.
13831351
headers | Link Headers Object | an Object representing headers to pass to the linked resource.
13841352
description | string | a description of the link, supports [CommonMark syntax](http://spec.commonmark.org/).
1385-
^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.
1353+
1354+
This object can be extended with [Specification Extensions](#specificationExtensions).
13861355

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

1796-
##### Patterned Objects
1797-
1798-
Field Pattern | Type | Description
1799-
---|:---:|---
1800-
<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.
1765+
This object can be extended with [Specification Extensions](#specificationExtensions).
18011766

18021767
##### Header Object Example
18031768

@@ -1827,10 +1792,7 @@ Field Name | Type | Description
18271792
<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.
18281793
<a name="tagExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag.
18291794

1830-
##### Patterned Fields
1831-
Field Pattern | Type | Description
1832-
---|:---:|---
1833-
<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.
1795+
This object can be extended with [Specification Extensions](#specificationExtensions).
18341796

18351797
##### Tag Object Example
18361798

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

2007-
##### Patterned Objects
2008-
2009-
Field Pattern | Type | Description
2010-
---|:---:|---
2011-
<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.
1969+
This object can be extended with [Specification Extensions](#specificationExtensions).
20121970

20131971
###### Composition and Inheritance (Polymorphism)
20141972

@@ -2410,11 +2368,7 @@ Field Name | Type | Description
24102368
<a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`.
24112369
<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`).
24122370

2413-
##### Patterned Objects
2414-
2415-
Field Pattern | Type | Description
2416-
---|:---:|---
2417-
<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.
2371+
This object can be extended with [Specification Extensions](#specificationExtensions).
24182372

24192373
##### XML Object Examples
24202374

@@ -2983,11 +2937,7 @@ Field Name | Type | Validity | Description
29832937
<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.
29842938
<a name="securitySchemeScopes"></a>scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme.
29852939

2986-
##### Patterned Fields
2987-
2988-
Field Name | Type | Description
2989-
---|:---:|---
2990-
<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.
2940+
This object can be extended with [Specification Extensions](#specificationExtensions).
29912941

29922942
##### Security Scheme Object Example
29932943

@@ -3052,11 +3002,7 @@ Field Pattern | Type | Description
30523002
---|:---:|---
30533003
<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).
30543004

3055-
##### Patterned Objects
3056-
3057-
Field Pattern | Type | Description
3058-
---|:---:|---
3059-
<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.
3005+
This object can be extended with [Specification Extensions](#specificationExtensions).
30603006

30613007
##### Scopes Object Example
30623008

@@ -3120,7 +3066,11 @@ petstore_auth:
31203066

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

3123-
The extensions properties are always prefixed by `"x-"` and can have any valid JSON format value.
3069+
The extensions properties are implemented as patterned fields that are always prefixed by `"x-"`.
3070+
3071+
Field Pattern | Type | Description
3072+
---|:---:|---
3073+
<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.
31243074

31253075
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).
31263076

0 commit comments

Comments
 (0)