Skip to content

Commit 4afb37a

Browse files
ralfhandlralfhandl
committed
Specification Extension instead of Vendor Extension
OAI#643
1 parent 86b99d3 commit 4afb37a

File tree

1 file changed

+22
-22
lines changed

1 file changed

+22
-22
lines changed

‎versions/3.0.md

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ This is the root document object for the API specification. It combines what pre
106106

107107
Field Name | Type | Description
108108
---|:---:|---
109-
<a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling vendors and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
109+
<a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
110110
<a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
111111
<a name="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
112112
<a name="oasConsumes"></a>consumes | [`string`] | A list of MIME types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Mime Types](#mimeTypes).
@@ -124,7 +124,7 @@ Field Name | Type | Description
124124

125125
Field Pattern | Type | Description
126126
---|:---:|---
127-
<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 [Vendor Extensions](#vendorExtensions) for further details.
127+
<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.
128128

129129
#### <a name="infoObject"></a>Info Object
130130

@@ -145,7 +145,7 @@ Field Name | Type | Description
145145

146146
Field Pattern | Type | Description
147147
---|:---:|---
148-
<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 [Vendor Extensions](#vendorExtensions) for further details.
148+
<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.
149149

150150
##### Info Object Example:
151151

@@ -209,7 +209,7 @@ Field Name | Type | Description
209209

210210
Field Pattern | Type | Description
211211
---|:---:|---
212-
<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 [Vendor Extensions](#vendorExtensions) for further details.
212+
<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.
213213

214214
##### Contact Object Example:
215215

@@ -242,7 +242,7 @@ Field Name | Type | Description
242242

243243
Field Pattern | Type | Description
244244
---|:---:|---
245-
<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 [Vendor Extensions](#vendorExtensions) for further details.
245+
<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.
246246

247247
##### License Object Example:
248248

@@ -268,7 +268,7 @@ The Paths may be empty, due to [ACL constraints](#securityFiltering).
268268
Field Pattern | Type | Description
269269
---|:---:|---
270270
<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.
271-
<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 [Vendor Extensions](#vendorExtensions) for further details.
271+
<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.
272272

273273
##### Paths Object Example
274274

@@ -339,7 +339,7 @@ Field Name | Type | Description
339339

340340
Field Pattern | Type | Description
341341
---|:---:|---
342-
<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 [Vendor Extensions](#vendorExtensions) for further details.
342+
<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.
343343

344344
##### Path Item Object Example
345345

@@ -445,7 +445,7 @@ Field Name | Type | Description
445445

446446
Field Pattern | Type | Description
447447
---|:---:|---
448-
<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 [Vendor Extensions](#vendorExtensions) for further details.
448+
<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.
449449

450450
##### Operation Object Example
451451

@@ -560,7 +560,7 @@ Field Name | Type | Description
560560

561561
Field Pattern | Type | Description
562562
---|:---:|---
563-
<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 [Vendor Extensions](#vendorExtensions) for further details.
563+
<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.
564564

565565
##### External Documentation Object Example
566566

@@ -633,7 +633,7 @@ Field Name | Type | Description
633633
##### Patterned Fields
634634
Field Pattern | Type | Description
635635
---|:---:|---
636-
<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 [Vendor Extensions](#vendorExtensions) for further details.
636+
<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.
637637

638638

639639
##### Parameter Object Examples
@@ -813,7 +813,7 @@ Field Name | Type | Description
813813

814814
Field Pattern | Type | Description
815815
---|:---:|---
816-
<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 [Vendor Extensions](#vendorExtensions) for further details.
816+
<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.
817817

818818
##### Items Object Examples
819819

@@ -869,7 +869,7 @@ Field Name | Type | Description
869869
Field Pattern | Type | Description
870870
---|:---:|---
871871
<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]`.
872-
<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 [Vendor Extensions](#vendorExtensions) for further details.
872+
<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.
873873

874874

875875
##### Responses Object Example
@@ -919,7 +919,7 @@ Field Name | Type | Description
919919

920920
Field Pattern | Type | Description
921921
---|:---:|---
922-
<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 [Vendor Extensions](#vendorExtensions) for further details.
922+
<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.
923923

924924
##### Response Object Examples
925925

@@ -1117,7 +1117,7 @@ Field Name | Type | Description
11171117

11181118
Field Pattern | Type | Description
11191119
---|:---:|---
1120-
<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 [Vendor Extensions](#vendorExtensions) for further details.
1120+
<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.
11211121

11221122
##### Header Object Example
11231123

@@ -1149,7 +1149,7 @@ Field Name | Type | Description
11491149
##### Patterned Fields
11501150
Field Pattern | Type | Description
11511151
---|:---:|---
1152-
<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 [Vendor Extensions](#vendorExtensions) for further details.
1152+
<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.
11531153

11541154
##### Tag Object Example
11551155

@@ -1171,7 +1171,7 @@ Anywhere an `example` may be given, allow a $ref object. This does mean that `e
11711171

11721172
In locations where the field being provided an `example` is a scalar value _or_ has it's content-type definition determined by a higher-level construct (a response payload, for example, uses the `produces` attribute to select the correct message format), the plural `examples` shall be used, and the payload format be specified as a key to the example.
11731173

1174-
In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling vendors may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible.
1174+
In all cases, the payload is expected to be compatible with the type schema for the value that it is accompanying. Tooling Specifications may choose to valide compatibility automatically, and reject the example value(s) if they are not compatible.
11751175

11761176
```yaml
11771177
# in a model
@@ -1310,7 +1310,7 @@ Field Name | Type | Description
13101310

13111311
Field Pattern | Type | Description
13121312
---|:---:|---
1313-
<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 [Vendor Extensions](#vendorExtensions) for further details.
1313+
<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.
13141314

13151315
###### Composition and Inheritance (Polymorphism)
13161316

@@ -1663,7 +1663,7 @@ Field Name | Type | Description
16631663

16641664
Field Pattern | Type | Description
16651665
---|:---:|---
1666-
<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 [Vendor Extensions](#vendorExtensions) for further details.
1666+
<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.
16671667

16681668
##### XML Object Examples
16691669

@@ -2008,7 +2008,7 @@ An object to hold data types that can be consumed and produced by operations. Th
20082008

20092009
Field Pattern | Type | Description
20102010
---|:---:|---
2011-
<a name="definitionsName"></a>{name} | [Schema Object](#schemaObject) | A single definition, mapping a "name" to the schema it defines. The following characters are legal in the `definitionsName`: `a-zA-Z0-9.-_\`. All other characters, including extended ASCII characters, are not legal in the `definitionsName`. The name may be used to namespace the definitions--it is the tooling vendor's job to ensure that the namespace is honored.
2011+
<a name="definitionsName"></a>{name} | [Schema Object](#schemaObject) | A single definition, mapping a "name" to the schema it defines. The following characters are legal in the `definitionsName`: `a-zA-Z0-9.-_\`. All other characters, including extended ASCII characters, are not legal in the `definitionsName`. The name may be used to namespace the definitions--it is the tooling Specification's job to ensure that the namespace is honored.
20122012

20132013
Examples:
20142014

@@ -2230,7 +2230,7 @@ Field Name | Type | Validity | Description
22302230

22312231
Field Name | Type | Description
22322232
---|:---:|---
2233-
<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 [Vendor Extensions](#vendorExtensions) for further details.
2233+
<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.
22342234

22352235
##### Security Scheme Object Example
22362236

@@ -2299,7 +2299,7 @@ Field Pattern | Type | Description
22992299

23002300
Field Pattern | Type | Description
23012301
---|:---:|---
2302-
<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 [Vendor Extensions](#vendorExtensions) for further details.
2302+
<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.
23032303

23042304
##### Scopes Object Example
23052305

@@ -2358,7 +2358,7 @@ petstore_auth:
23582358
- read:pets
23592359
```
23602360

2361-
### <a name="vendorExtensions"></a>Specification Extensions
2361+
### <a name="specificationExtensions"></a>Specification Extensions
23622362

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

0 commit comments

Comments
 (0)