Explain dynamic refs for generics (3.2.0 port of #3714)

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,119 @@ 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:
+    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
+```
+
 #### <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.