oas.md.diff

--- 3.0.0.md	2023-12-09 17:21:54
+++ 3.0.1.md	2023-12-09 17:21:54
@@ -1,10 +1,10 @@
 # OpenAPI Specification
 
-#### Version 3.0.0
+#### Version 3.0.1
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.
 
-This document is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
+This document is licensed under [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).
 
 ## Introduction
 
@@ -75,7 +75,7 @@
 
 ##### <a name="mediaTypes"></a>Media Types
 Media type definitions are spread across several resources.
-The media type definitions SHOULD be in compliance with [RFC6838](http://tools.ietf.org/html/rfc6838).
+The media type definitions SHOULD be in compliance with [RFC6838](https://tools.ietf.org/html/rfc6838).
 
 Some examples of possible media type definitions:
 ```
@@ -92,13 +92,13 @@
 ```
 ##### <a name="httpCodes"></a>HTTP Status Codes
 The HTTP Status Codes are used to indicate the status of the executed operation. 
-The available status codes are defined by [RFC7231](http://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+The available status codes are defined by [RFC7231](https://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
 
 ## Specification
 
 ### Versions
 
-The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](http://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
+The OpenAPI Specification is versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.
 
 The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.
 
@@ -188,7 +188,7 @@
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://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.
+<a name="oasVersion"></a>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.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
 <a name="oasServers"></a>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 `/`.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
@@ -232,7 +232,7 @@
   },
   "license": {
     "name": "Apache 2.0",
-    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
   },
   "version": "1.0.1"
 }
@@ -248,7 +248,7 @@
   email: support@example.com
 license:
   name: Apache 2.0
-  url: http://www.apache.org/licenses/LICENSE-2.0.html
+  url: https://www.apache.org/licenses/LICENSE-2.0.html
 version: 1.0.1
 ```
 
@@ -300,13 +300,13 @@
 ```json
 {
   "name": "Apache 2.0",
-  "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
 }
 ```
 
 ```yaml
 name: Apache 2.0
-url: http://www.apache.org/licenses/LICENSE-2.0.html
+url: https://www.apache.org/licenses/LICENSE-2.0.html
 ```
 
 #### <a name="serverObject"></a>Server Object
@@ -1004,8 +1004,8 @@
 <a name="parameterExplode"></a>explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map.  For other types of parameters this property has no effect. When [`style`](#parameterStyle) is `form`, the default value is `true`. For all other styles, the default value is `false`.
 <a name="parameterAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. This property only applies to parameters with an `in` value of `query`. The default value is `false`.
 <a name="parameterSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the parameter.
-<a name="parameterExample"></a>example | Any | Example of the media type.  The example SHOULD match the specified schema and encoding properties if present.  The `example` object is mutually exclusive of the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
-<a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example SHOULD contain a value in the correct format as specified in the parameter encoding.  The `examples` object is mutually exclusive of the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
+<a name="parameterExample"></a>example | Any | Example of the media type.  The example SHOULD match the specified schema and encoding properties if present.  The `example` field is mutually exclusive of the `examples` field.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema. To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.
+<a name="parameterExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example SHOULD contain a value in the correct format as specified in the parameter encoding.  The `examples` field is mutually exclusive of the `example` field.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 
 For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter.
 A parameter MUST contain either a `schema` property, or a `content` property, but not both.
@@ -1343,8 +1343,8 @@
 Field Name | Type | Description
 ---|:---:|---
 <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body.
-<a name="mediaTypeExample"></a>example | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  The `example` object is mutually exclusive of the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.
-<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  The `examples` object is mutually exclusive of the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
+<a name="mediaTypeExample"></a>example | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  The `example` field is mutually exclusive of the `examples` field.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.
+<a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  The `examples` field is mutually exclusive of the `example` field.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
 <a name="mediaTypeEncoding"></a>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 object SHALL only apply to `requestBody` objects when the media type is `multipart` or `application/x-www-form-urlencoded`.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -1737,7 +1737,7 @@
 
 ```yaml
 description: A simple string response
-representations:
+content:
   text/plain:
     schema:
       type: string
@@ -2018,13 +2018,13 @@
                   uuid: # the unique user id
                     type: string
                     format: uuid
-        links:
-          address:
-            # the target link operationId
-            operationId: getUserAddress
-            parameters:
-              # get the `id` field from the request path parameter named `id`
-              userId: $request.path.id
+          links:
+            address:
+              # the target link operationId
+              operationId: getUserAddress
+              parameters:
+                # get the `id` field from the request path parameter named `id`
+                userId: $request.path.id
   # the path item of the linked operation
   /users/{userid}/address:
     parameters:
@@ -2034,12 +2034,12 @@
       description: the user identifier, as userId 
       schema:
         type: string
-      # linked operation
-      get:
-        operationId: getUserAddress
-        responses:
-          '200':
-            description: the user's address
+    # linked operation
+    get:
+      operationId: getUserAddress
+      responses:
+        '200':
+          description: the user's address
 ```
 
 When a runtime expression fails to evaluate, no parameter value is passed to the target operation.
@@ -2051,7 +2051,7 @@
   address:
     operationId: getUserAddressByUUID
     parameters:
-      # get the `id` field from the request path parameter named `id`
+      # get the `uuid` field from the `uuid` field in the response body
       userUuid: $response.body#/uuid
 ```
 
@@ -2183,69 +2183,7 @@
 description: Pets operations
 ```
 
-#### <a name="examplesObject"></a>Examples Object
 
-In an `example`, a JSON Reference MAY be used, with the 
-explicit restriction that examples having a JSON format with object named 
-`$ref` are not allowed. Therefore, that `example`, structurally, can be 
-either a string primitive or an object, similar to `additionalProperties`.
-
-In all cases, the payload is expected to be compatible with the type schema 
-for the associated value.  Tooling implementations MAY choose to 
-validate compatibility automatically, and reject the example value(s) if they 
-are incompatible.
-
-```yaml
-# in a model
-schemas:
-  properties:
-    name:
-      type: string
-      example:
-        $ref: http://foo.bar#/examples/name-example
-
-# in a request body, note the plural `examples`
-  requestBody:
-    content:
-      'application/json':
-        schema:
-          $ref: '#/components/schemas/Address'
-        examples:
-          foo:
-            value: {"foo": "bar"}
-          bar:
-            value: {"bar": "baz"}
-      'application/xml':
-        examples:
-          xml:
-            externalValue: 'http://foo.bar/examples/address-example.xml'
-      'text/plain':
-        examples:
-          text:
-            externalValue: 'http://foo.bar/examples/address-example.txt'
-        
-# in a parameter
-  parameters:
-    - name: 'zipCode'
-      in: 'query'
-      schema:
-        type: 'string'
-        format: 'zip-code'
-        example: 
-          $ref: 'http://foo.bar#/examples/zip-example'
-
-# in a response, note the singular `example`:
-  responses:
-    '200':
-      description: your car appointment has been booked
-      content: 
-        application/json:
-          schema:
-            $ref: '#/components/schemas/SuccessResponse'
-          example:
-            $ref: http://foo.bar#/examples/address-example.json
-```
-
 #### <a name="referenceObject"></a>Reference Object
 
 A simple object to allow referencing other components in the specification, internally and externally.
@@ -2367,7 +2305,7 @@
 To support polymorphism, the OpenAPI Specification adds the `discriminator` field.
 When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model.
 As such, the `discriminator` field MUST be a required field.
-There are are two ways to define the value of a discriminator for an inheriting instance.
+There are two ways to define the value of a discriminator for an inheriting instance.
 - Use the schema name.
 - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
 As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism.
@@ -3430,6 +3368,7 @@
 
 Version   | Date       | Notes
 ---       | ---        | ---
+3.0.1     | 2017-12-06 | Patch release of the OpenAPI Specification 3.0.1
 3.0.0     | 2017-07-26 | Release of the OpenAPI Specification 3.0.0
 3.0.0-rc2 | 2017-06-16 | rc2 of the 3.0 specification
 3.0.0-rc1 | 2017-04-27 | rc1 of the 3.0 specification