Merge pull request #4573 from handrews/312-port

v3.2: Port of 3.1.2 changes to 3.2

Author: lornajane

src/oas.md

@@ -230,7 +230,7 @@ In some cases, an unambiguous URI-based alternative is available, and OAD author
 | [Security Requirement Object](#security-requirement-object) `{name}` | [Security Scheme Object](#security-scheme-object) name under the [Components Object](#components-object) | _n/a_ |
 | [Discriminator Object](#discriminator-object) `mapping` _(implicit, or explicit name syntax)_ | [Schema Object](#schema-object) name under the Components Object | `mapping` _(explicit URI syntax)_ |
 | [Operation Object](#operation-object) `tags` | [Tag Object](#tag-object) `name` (in the [OpenAPI Object](#openapi-object)'s `tags` array) | _n/a_ |
-| [Link Object](#link-object) `operationId` | [Path Item Object](#path-item-object) `operationId` | `operationRef` |
+| [Link Object](#link-object) `operationId` | [Operation Object](#operation-object) `operationId` | `operationRef` |
 
 A fifth implicit connection involves appending the templated URL paths of the [Paths Object](#paths-object) to the appropriate [Server Object](#server-object)'s `url` field.
 This is unambiguous because only the entry document's Paths Object contributes URLs to the described API.
@@ -252,7 +252,7 @@ There are no URI-based alternatives for the Operation Object's `tags` field.
 OAD authors are advised to use external solutions such as the OpenAPI Initiative's Overlay Specification to simulate sharing [Tag Objects](#tag-object) across multiple documents.
 
 See [Appendix F: Resolving Security Requirements in a Referenced Document](#appendix-f-resolving-security-requirements-in-a-referenced-document) for an example of the possible resolutions, including which one is recommended by this section.
-The behavior for Discrimator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles.
+The behavior for Discriminator Object non-URI mappings and for the Operation Object's `tags` field operate on the same principles.
 
 Note that no aspect of implicit connection resolution changes how [URIs are resolved](#relative-references-in-api-description-uris), or restricts their possible targets.
 
@@ -509,7 +509,7 @@ An object representing a Server.
 
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
-| <a name="server-url"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Variable substitutions will be made when a variable is named in `{`braces`}`. |
+| <a name="server-url"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the document containing the Server Object is being served. Query and fragment MUST NOT be part of this URL. Variable substitutions will be made when a variable is named in `{`braces`}`. |
 | <a name="server-description"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
 | <a name="server-name"></a>name | `string` | An optional unique string to refer to the host designated by the URL. |
 | <a name="server-variables"></a>variables | Map[`string`, [Server Variable Object](#server-variable-object)] | A map between a variable name and its value. The value is used for substitution in the server's URL template. |
@@ -2139,8 +2139,9 @@ requestBody:
           name:
             type: string
           icon:
-            # The default with "contentEncoding" is application/octet-stream,
-            # so we need to set image media type(s) in the Encoding Object.
+            # The default content type with "contentEncoding" present
+            # is application/octet-stream, so we need to set the correct
+            # image media type(s) in the Encoding Object.
             type: string
             contentEncoding: base64url
   encoding:
@@ -2186,18 +2187,22 @@ requestBody:
       schema:
         type: object
         properties:
+          # default content type for a string without `contentEncoding`
+          # is `text/plain`
           id:
-            # default for primitives without a special format is text/plain
             type: string
             format: uuid
-          profileImage:
-            # default for string with binary format is `application/octet-stream`
-            type: string
-            format: binary
+
+          # default content type for a schema without `type`
+          # is `application/octet-stream`
+          profileImage: {}
+
+          # for arrays, the `encoding` field applies the Encoding Object
+          # to each item individually and determines the default content type
+          # based on the type in the `items` subschema, which in this example
+          # is an object, so the default content type for each item is
+          # `application/json`
           addresses:
-            # for arrays, the Encoding Object applies to each item
-            # individually based on that item's type, which in this
-            # example is an object, so `application/json`
             type: array
             items:
               $ref: '#/components/schemas/Address'
@@ -2215,31 +2220,27 @@ requestBody:
       schema:
         type: object
         properties:
+          # No Encoding Object, so use default `text/plain`
           id:
-            # default is `text/plain`
             type: string
             format: uuid
+
+          # Encoding Object overrides the default `application/json` content type
+          # for each item in the array with `application/xml; charset=utf-8`
           addresses:
-            # default based on the `items` subschema would be
-            # `application/json`, but we want these address objects
-            # serialized as `application/xml` instead
             description: addresses in XML format
             type: array
             items:
               $ref: '#/components/schemas/Address'
-          profileImage:
-            # default is application/octet-stream, but we can declare
-            # a more specific image type or types
-            type: string
-            format: binary
+
+          # Encoding Object accepts only PNG or JPEG, and also describes
+          # a custom header for just this part in the multipart format
+          profileImage: {}
+
       encoding:
         addresses:
-          # require XML Content-Type in utf-8 encoding
-          # This is applied to each address part corresponding
-          # to each address in he array
           contentType: application/xml; charset=utf-8
         profileImage:
-          # only accept png or jpeg
           contentType: image/png, image/jpeg
           headers:
             X-Rate-Limit-Limit:
@@ -2598,19 +2599,19 @@ Tooling implementations MAY choose to validate compatibility automatically, and
 
 ##### Working with Examples
 
-Example Objects can be used in both [Parameter Objects](#parameter-object) and [Media Type Objects](#media-type-object).
-In both Objects, this is done through the `examples` (plural) field.
-However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in both Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of both Objects.
+Example Objects can be used in [Parameter Objects](#parameter-object), [Header Objects](#header-object), and [Media Type Objects](#media-type-object).
+In all three Objects, this is done through the `examples` (plural) field.
+However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in all three Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of all three Objects.
 Each of these fields has slightly different considerations.
 
 The Schema Object's fields are used to show example values without regard to how they might be formatted as parameters or within media type representations.
 The `examples` array is part of JSON Schema and is the preferred way to include examples in the Schema Object, while `example` is retained purely for compatibility with older versions of the OpenAPI Specification.
 
-The mutually exclusive fields in the Parameter or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation.
-The exact serialization and encoding is determined by various fields in the Parameter Object, or in the Media Type Object's [Encoding Object](#encoding-object).
+The mutually exclusive fields in the Parameter, Header, or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter, serialized header, or within a media type representation.
+The exact serialization and encoding is determined by various fields in the Parameter Object, Header Object, or in the Media Type Object's [Encoding Object](#encoding-object).
 Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object.
 
-The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`.
+The singular `example` field in the Parameter, Header, or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`.
 
 Some examples cannot be represented directly in JSON or YAML.
 For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of documents that comprise the OpenAPI Description.
@@ -2773,7 +2774,7 @@ For computing links and providing instructions to execute them, a [runtime expre
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
 A linked operation MUST be identified using either an `operationRef` or `operationId`.
-The identified or reference operation MUST be unique, and in the case of an `operationId`, it MUST be resolved within the scope of the OpenAPI Description (OAD).
+The identified or referenced operation MUST be unique, and in the case of an `operationId`, it MUST be resolved within the scope of the OpenAPI Description (OAD).
 Because of the potential for name clashes, the `operationRef` syntax is preferred for multi-document OADs.
 However, because use of an operation depends on its URL path template in the [Paths Object](#paths-object), operations from any [Path Item Object](#path-item-object) that is referenced multiple times within the OAD cannot be resolved unambiguously.
 In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error.
@@ -4505,7 +4506,7 @@ flows:
 
 Lists the required security schemes to execute this operation.
 
-The name used for each property MUST either correspond to a security scheme declared in the [Security Schemes](#security-scheme-object) under the [Components Object](#components-object), or be the URI of a Security Scheme Object.
+The name used for each property MUST either correspond to a security scheme declared in the [Security Schemes](#components-security-schemes) under the [Components Object](#components-object), or be the URI of a Security Scheme Object.
 Property names that are identical to a component name under the Components Object MUST be treated as a component name.
 To reference a Security Scheme with a single-segment relative URI reference (e.g. `foo`) that collides with a component name (e.g. `#/components/securitySchemes/foo`), use the `.` path segment (e.g. `./foo`).
 
@@ -5023,7 +5024,7 @@ This specification normatively cites the following relevant standards:
 Style-based serialization is used in the [Parameter Object](#parameter-object) when `schema` is present, and in the [Encoding Object](#encoding-object) when at least one of `style`, `explode`, or `allowReserved` is present.
 See [Appendix C](#appendix-c-using-rfc6570-based-serialization) for more details of RFC6570's two different approaches to percent-encoding, including an example involving `+`.
 
-Content-based serialization is defined by the [Media Type Object](#media-type-object), and used with the [Parameter Object](#parameter-object) when the `content` field is present, and with the [Encoding Object](#encoding-object) based on the `contentType` field when the fields `style`, `explode`, and `allowReserved` are absent.
+Content-based serialization is defined by the [Media Type Object](#media-type-object), and used with the [Parameter Object](#parameter-object) and [Header Object](#header-object) when the `content` field is present, and with the [Encoding Object](#encoding-object) based on the `contentType` field when the fields `style`, `explode`, and `allowReserved` are absent.
 Each part is encoded based on the media type (e.g. `text/plain` or `application/json`), and must then be percent-encoded for use in a `form-urlencoded` string.
 
 Note that content-based serialization for `form-data` does not expect or require percent-encoding in the data, only in per-part header values.

src/schemas/validation/schema.yaml

@@ -12,7 +12,7 @@ properties:
     $ref: '#/$defs/info'
   jsonSchemaDialect:
     type: string
-    format: uri
+    format: uri-reference
     default: 'https://spec.openapis.org/oas/3.2/dialect/WORK-IN-PROGRESS'
   servers:
     type: array
@@ -64,7 +64,7 @@ $defs:
         type: string
       termsOfService:
         type: string
-        format: uri
+        format: uri-reference
       contact:
         $ref: '#/$defs/contact'
       license:
@@ -85,7 +85,7 @@ $defs:
         type: string
       url:
         type: string
-        format: uri
+        format: uri-reference
       email:
         type: string
         format: email
@@ -102,7 +102,7 @@ $defs:
         type: string
       url:
         type: string
-        format: uri
+        format: uri-reference
     required:
       - name
     dependentSchemas:
@@ -319,7 +319,7 @@ $defs:
         type: string
       url:
         type: string
-        format: uri
+        format: uri-reference
     required:
       - url
     $ref: '#/$defs/specification-extensions'
@@ -620,7 +620,7 @@ $defs:
       value: true
       externalValue:
         type: string
-        format: uri
+        format: uri-reference
     not:
       required:
       - value
@@ -864,7 +864,7 @@ $defs:
           properties:
             openIdConnectUrl:
               type: string
-              format: uri
+              format: uri-reference
           required:
             - openIdConnectUrl
 
@@ -900,10 +900,10 @@ $defs:
         properties:
           authorizationUrl:
             type: string
-            format: uri
+            format: uri-reference
           refreshUrl:
             type: string
-            format: uri
+            format: uri-reference
           scopes:
             $ref: '#/$defs/map-of-strings'
         required:
@@ -917,10 +917,10 @@ $defs:
         properties:
           tokenUrl:
             type: string
-            format: uri
+            format: uri-reference
           refreshUrl:
             type: string
-            format: uri
+            format: uri-reference
           scopes:
             $ref: '#/$defs/map-of-strings'
         required:
@@ -934,10 +934,10 @@ $defs:
         properties:
           tokenUrl:
             type: string
-            format: uri
+            format: uri-reference
           refreshUrl:
             type: string
-            format: uri
+            format: uri-reference
           scopes:
             $ref: '#/$defs/map-of-strings'
         required:
@@ -951,13 +951,13 @@ $defs:
         properties:
           authorizationUrl:
             type: string
-            format: uri
+            format: uri-reference
           tokenUrl:
             type: string
-            format: uri
+            format: uri-reference
           refreshUrl:
             type: string
-            format: uri
+            format: uri-reference
           scopes:
             $ref: '#/$defs/map-of-strings'
         required: