Merge pull request #3795 from handrews/generics-320

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

versions/3.2.0.md

@@ -2420,6 +2420,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.
@@ -2763,6 +2772,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.