Explain dynamic refs for generics (3.2.0)

Includes an example.  This intentionally does not explain how
dynamic referencing works, as there are better resources available
in both the spec and (more readably) the official JSON Schema blog.

Author: handrews

versions/3.2.0.md

@@ -2398,6 +2398,15 @@ There are two ways to define the value of a discriminator for an inheriting inst
 - 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.
 
+###### Generic (Template) Data Structures
+
+Implementations MAY support defining generic or template data structures using JSON Schema's dynamic referencing feature:
+
+* `$dynamicAnchor` identifies a set of possible schemas (including a default placeholder schema) to which a `$dynamicRef` can resolve
+* `$dynamicRef` resolves to the first matching `$dynamicAnchor` encountered on its path from the schema entry point to the reference, as described in the JSON Schema specification
+
+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.
+
 ###### XML Modeling
 
 The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML.
@@ -2741,6 +2750,111 @@ components:
         - packSize
 ```
 
+###### Generic Data Structure Model
+
+```JSON
+{
+  "components": {
+    "schemas": {
+      "genericArrayComponent": {
+        "$id": "fully_generic_array",
+        "type": "array",
+        "items": {
+          "$dynamicRef": "#generic-array"
+        },
+        "$defs": {
+          "allowAll": {
+            "$dynamicAnchor": "generic-array"
+          }
+        }
+      },
+      "numberArray": {
+        "$id": "array_of_numbers",
+        "$ref": "fully_generic_array",
+        "$defs": {
+          "numbersOnly": {
+            "$dynamicAnchor": "generic-array",
+            "type": "number"
+          }
+        }
+      },
+      "stringArray": {
+        "$id": "array_of_strings",
+        "$ref": "fully_generic_array",
+        "$defs": {
+          "stringsOnly": {
+            "$dynamicAnchor": "generic-array",
+            "type": "string"
+          }
+        }
+      },
+      "objWithTypedArray": {
+        "$id": "obj_with_typed_array",
+        "type": "object",
+        "required": ["dataType", "data"],
+        "properties": {
+          "dataType": {
+            "enum": ["string", "number"]
+          }
+        },
+        "oneOf": [{
+          "properties": {
+            "dataType": {"const": "string"},
+            "data": {"$ref": "array_of_strings"}
+          }
+        }, {
+          "properties": {
+            "dataType": {"const": "number"},
+            "data": {"$ref": "array_of_numbers"}
+          }
+        }]
+      }
+    }
+  }
+}
+```
+
+```YAML
+components:
+  schemas:
+    genericArray:
+      $id: fully_generic_array
+      type: array
+      items:
+        $dynamicRef: "#generic-array"
+      $defs:
+        allowAll:
+          $dynamicAnchor: generic-array
+    numberArray:
+      $id: array_of_numbers
+      $ref: fully_generic_array
+      $defs:
+        numbersOnly:
+          $dynamicAnchor: generic-array
+          type: number
+    stringArray:
+      $id: array_of_strings
+      $ref: fully_generic_array
+      $defs:
+        stringsOnly:
+          $dynamicAnchor: generic-array
+          type: string
+    objWithTypedArray:
+      $id: obj_with_typed_array
+      type: object
+      required: [dataType, data]
+      properties:
+        dataType:
+          enum: [string, number]
+      oneOf:
+      - properties:
+          dataType: {const: string}
+          data: {$ref: array_of_strings}
+      - properties:
+          dataType: {const: number}
+          data: {$ref: array_of_numbers}
+```
+
 #### <a name="discriminatorObject"></a>Discriminator Object
 
 When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object can be used to aid in serialization, deserialization, and validation.  The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.