Annotated enums and extended validation

This tidies up the increasingly long Schema Object section and adds
explanations of what I've been calling "extended validation",
including validating `readOnly` and `writeOnly`, and also using
a `oneOf` or `anyOf` with `const` plus annotations for enumerated
types with additional information.

There are many OAS issues/discussions where we have recommended
these techniques, so it makes sense to include them in 3.1.1 where
draft 2020-12's formal collection of annotations enables tools
to build support for them.

Author: handrews

versions/3.1.1.md

@@ -2758,6 +2758,28 @@ 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.
+
+###### 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 +2803,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.