From ff21dee16542df8e695063981633dfbe474fbdc3 Mon Sep 17 00:00:00 2001
From: "Henry H. Andrews" <andrews_henry@yahoo.com>
Date: Wed, 20 Mar 2024 10:52:31 -0700
Subject: [PATCH] Explain that dynamic refs can implement generics

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.

Thanks to Ralf for review feedback fixes on the original 3.2.0 PR

Co-authored-by: Ralf Handl <ralf.handl@sap.com>
---
 versions/3.2.0.md | 122 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 122 insertions(+)

diff --git a/versions/3.2.0.md b/versions/3.2.0.md
index 5037aeb318..e33d9e2561 100644
--- a/versions/3.2.0.md
+++ b/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.