Skip to content

Commit 15accef

Browse files
fehguyfehguy
committed
Merge pull request OAI#657 from ralfhandl/patch-2
Specification Extension instead of Vendor Extension
2 parents c0db8e3 + 4afb37a commit 15accef

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).
@@ -122,7 +122,7 @@ Field Name | Type | Description
122122

123123
Field Pattern | Type | Description
124124
---|:---:|---
125-
<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.
125+
<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.
126126

127127
#### <a name="infoObject"></a>Info Object
128128

@@ -143,7 +143,7 @@ Field Name | Type | Description
143143

144144
Field Pattern | Type | Description
145145
---|:---:|---
146-
<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.
146+
<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.
147147

148148
##### Info Object Example:
149149

@@ -207,7 +207,7 @@ Field Name | Type | Description
207207

208208
Field Pattern | Type | Description
209209
---|:---:|---
210-
<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.
210+
<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.
211211

212212
##### Contact Object Example:
213213

@@ -240,7 +240,7 @@ Field Name | Type | Description
240240

241241
Field Pattern | Type | Description
242242
---|:---:|---
243-
<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.
243+
<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.
244244

245245
##### License Object Example:
246246

@@ -281,7 +281,7 @@ The Paths may be empty, due to [ACL constraints](#securityFiltering).
281281
Field Pattern | Type | Description
282282
---|:---:|---
283283
<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.
284-
<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.
284+
<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.
285285

286286
##### Paths Object Example
287287

@@ -352,7 +352,7 @@ Field Name | Type | Description
352352

353353
Field Pattern | Type | Description
354354
---|:---:|---
355-
<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.
355+
<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.
356356

357357
##### Path Item Object Example
358358

@@ -458,7 +458,7 @@ Field Name | Type | Description
458458

459459
Field Pattern | Type | Description
460460
---|:---:|---
461-
<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.
461+
<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.
462462

463463
##### Operation Object Example
464464

@@ -573,7 +573,7 @@ Field Name | Type | Description
573573

574574
Field Pattern | Type | Description
575575
---|:---:|---
576-
<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.
576+
<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.
577577

578578
##### External Documentation Object Example
579579

@@ -623,7 +623,7 @@ Field Name | Type | Description
623623
##### Patterned Fields
624624
Field Pattern | Type | Description
625625
---|:---:|---
626-
<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.
626+
<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.
627627

628628

629629
##### Parameter Object Examples
@@ -815,7 +815,7 @@ Field Name | Type | Description
815815

816816
Field Pattern | Type | Description
817817
---|:---:|---
818-
<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.
818+
<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.
819819

820820
##### Items Object Examples
821821

@@ -871,7 +871,7 @@ Field Name | Type | Description
871871
Field Pattern | Type | Description
872872
---|:---:|---
873873
<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]`.
874-
<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.
874+
<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.
875875

876876

877877
##### Responses Object Example
@@ -921,7 +921,7 @@ Field Name | Type | Description
921921

922922
Field Pattern | Type | Description
923923
---|:---:|---
924-
<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.
924+
<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.
925925

926926
##### Response Object Examples
927927

@@ -1119,7 +1119,7 @@ Field Name | Type | Description
11191119

11201120
Field Pattern | Type | Description
11211121
---|:---:|---
1122-
<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.
1122+
<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.
11231123

11241124
##### Header Object Example
11251125

@@ -1151,7 +1151,7 @@ Field Name | Type | Description
11511151
##### Patterned Fields
11521152
Field Pattern | Type | Description
11531153
---|:---:|---
1154-
<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.
1154+
<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.
11551155

11561156
##### Tag Object Example
11571157

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

11741174
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.
11751175

1176-
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.
1176+
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.
11771177

11781178
```yaml
11791179
# in a model
@@ -1312,7 +1312,7 @@ Field Name | Type | Description
13121312

13131313
Field Pattern | Type | Description
13141314
---|:---:|---
1315-
<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.
1315+
<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.
13161316

13171317
###### Composition and Inheritance (Polymorphism)
13181318

@@ -1665,7 +1665,7 @@ Field Name | Type | Description
16651665

16661666
Field Pattern | Type | Description
16671667
---|:---:|---
1668-
<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.
1668+
<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.
16691669

16701670
##### XML Object Examples
16711671

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

20112011
Field Pattern | Type | Description
20122012
---|:---:|---
2013-
<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.
2013+
<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.
20142014

20152015
Examples:
20162016

@@ -2232,7 +2232,7 @@ Field Name | Type | Validity | Description
22322232

22332233
Field Name | Type | Description
22342234
---|:---:|---
2235-
<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.
2235+
<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.
22362236

22372237
##### Security Scheme Object Example
22382238

@@ -2301,7 +2301,7 @@ Field Pattern | Type | Description
23012301

23022302
Field Pattern | Type | Description
23032303
---|:---:|---
2304-
<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.
2304+
<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.
23052305

23062306
##### Scopes Object Example
23072307

@@ -2360,7 +2360,7 @@ petstore_auth:
23602360
- read:pets
23612361
```
23622362

2363-
### <a name="vendorExtensions"></a>Specification Extensions
2363+
### <a name="specificationExtensions"></a>Specification Extensions
23642364

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

0 commit comments

Comments
 (0)