Merge pull request #4111 from handrews/extended

Annotated enums and extended validation

versions/3.1.1.md

@@ -2758,6 +2758,31 @@ JSON Schema implementations MAY choose to treat keywords defined by the OpenAPI
 
 This object MAY be extended with [Specification Extensions](#specification-extensions), though as noted, additional properties MAY omit the `x-` prefix within this object.
 
+##### Extended Validation with Annotations
+
+JSON Schema Draft 2020-12 supports [collecting annotations](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-7.7.1), including [treating unrecognized keywords as annotations](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-6.5).
+OAS implementations MAY use such annotations, including [extensions](https://spec.openapis.org/registry/extension/) not recognized as part of a declared JSON Schema vocabulary, as the basis for further validation.
+Note that JSON Schema Draft 2020-12 does not require an `x-` prefix for extensions.
+
+###### Non-validating constraint keywords
+
+The [`format` keyword (when using default format-annotation vocabulary)](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.1) and the [`contentMediaType`, `contentEncoding`, and `contentSchema` keywords](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-8.2) define constraints on the data, but are treated as annotations instead of being validated directly.
+Extended validation is one way that these constraints MAY be enforced.
+
+###### Validating `readOnly` and `writeOnly`
+
+The `readOnly` and `writeOnly` keywords are annotations, as JSON Schema is not aware of how the data it is validating is being used.
+Validation of these keywords MAY be done by checking the annotation, the read or write direction, and (if relevant) the current value of the field.
+[JSON Schema Validation Draft 2020-12 §9.4](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-9.4) defines the expectations of these keywords, including that a resource (described as the "owning authority") MAY either ignore a `readOnly` field or treat it as an error.
+
+Fields that are both required and read-only are an example of when it is beneficial to ignore a `readOnly: true` constraint in a PUT, particularly if the value has not been changed.
+This allows correctly requiring the field on a GET and still using the same representation and schema with PUT.
+Even when read-only fields are not required, stripping them is burdensome for clients, particularly when the JSON data is complex or deeply nested.
+
+Note that the behavior of `readOnly` in particular differs from that specified by version 3.0 of this specification.
+
+##### Data Modeling Techniques
+
 ###### Composition and Inheritance (Polymorphism)
 
 The OpenAPI Specification allows combining and extending model definitions using the `allOf` keyword of JSON Schema, in effect offering model composition.
@@ -2781,12 +2806,18 @@ Implementations MAY support defining generic or template data structures using J
 
 An example is included in the "Schema Object Examples" section below, and further information can be found on the Learn OpenAPI site's ["Dynamic References"](https://learn.openapis.org/referencing/dynamic.html) page.
 
+###### Annotated Enumerations
+
+The Schema Object's `enum` keyword does not allow associating descriptions or other information with individual values.
+
+Implementations MAY support recognizing a `oneOf` or `anyOf` where each subschema in the keyword's array consists of a `const` keyword and annotations such as `title` or `description` as an enumerated type with additional information. The exact behavior of this pattern beyond what is required by JSON Schema is implementation-defined.
+
 ###### XML Modeling
 
 The [xml](#schema-xml) field allows extra definitions when translating the JSON definition to XML.
 The [XML Object](#xml-object) contains additional information about the available options.
 
-###### Specifying Schema Dialects
+##### Specifying Schema Dialects
 
 It is important for tooling to be able to determine which dialect or meta-schema any given resource wishes to be processed with: JSON Schema Core, JSON Schema Validation, OpenAPI Schema dialect, or some custom meta-schema.
 
@@ -2886,6 +2917,35 @@ additionalProperties:
   $ref: '#/components/schemas/ComplexModel'
 ```
 
+###### Model with Annotated Enumeration
+
+```json
+{
+  "oneOf": [
+    {
+      "const": "RGB",
+      "title": "Red, Green, Blue",
+      "description": "Specify colors with the red, green, and blue additive color model"
+    },
+    {
+      "const": "CMYK",
+      "title": "Cyan, Magenta, Yellow, Black",
+      "description": "Specify colors with the cyan, magenta, yellow, and black subtractive color model"
+    }
+  ]
+}
+```
+
+```yaml
+oneOf:
+  - const: RGB
+    title: Red, Green, Blue
+    description: Specify colors with the red, green, and blue additive color model
+  - const: CMYK
+    title: Cyan, Magenta, Yellow, Black
+    description: Specify colors with the cyan, magenta, yellow, and black subtractive color model
+```
+
 ###### Model with Example
 
 ```json
@@ -4465,7 +4525,7 @@ This keeps it outside of the processes governed by this specification.
 
 ## Appendix F: Resolving Security Requirements in a Referenced Document
 
-This appendix shows how to retrieve an HTTP-accessible multi-document OpenAPI Description (OAD) and resolve a [Security Requirement Object](#security-requirement-object) in the referenced (non-entry) document.  See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
+This appendix shows how to retrieve an HTTP-accessible multi-document OpenAPI Description (OAD) and resolve a [Security Requirement Object](#security-requirement-object) in the referenced (non-entry) document. See [Resolving Implicit Connections](#resolving-implicit-connections) for more information.
 
 First, the [entry document](#openapi-description-structure) is where parsing begins. It defines the `MySecurity` security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:
 
@@ -4510,7 +4570,7 @@ paths:
     $ref: 'other#/components/pathItems/Foo'
 ```
 
-This entry document references another document, `other`, without using a file extension.  This gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:
+This entry document references another document, `other`, without using a file extension. This gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:
 
 ```HTTP
 GET /api/description/other HTTP/1.1