Annotated enums and extended validation

versions/3.1.1.md

@@ -2758,6 +2758,29 @@ 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 resource (described as the "owning authority") MAY either ignore a `readOnly` field or treat it as an error.
+
+An example of  where ignoring a "written" `readOnly` field might be appropriate is a PUT request where the field is included but the value has not been changed, since the alternative of leaving out the field would result in the field's deletion per [[RFC7231]].
+
+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 +2804,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 +2915,32 @@ 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