From 3cff10ae8f8dee0f1701cab8b5ba154f9c13e087 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 20 Mar 2024 10:52:31 -0700 Subject: [PATCH 1/8] 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. --- versions/3.1.1.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e4423df5b2..f429dbb4b1 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2346,6 +2346,13 @@ While composition offers model extensibility, it does not imply a hierarchy betw To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword. When used, the `discriminator` indicates the name of the property that hints which schema definition is expected to validate the structure of the model. +###### Generic (Template) Data Structures + +Implementations MAY support defining generic or template data structures using JSON Schema's dynamic referencing feature: + +* `$dynamicAnchor` identifies set of possible schemas (including a default placeholder schema) to which a `$dynamicRef` can resolve +* `$dynamicRef` resolves to the first matching encountered on its path from the schema entry point to the reference, as described in the JSON Schema specification + ###### XML Modeling The [xml](#schemaXml) property allows extra definitions when translating the JSON definition to XML. @@ -2689,6 +2696,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} +``` + #### Discriminator Object When request bodies or response payloads may be one of a number of different schemas, a `discriminator` object gives a hint about the expected schema of the document. It can be used to aid in serialization, deserialization, and validation. From 9c07b82e058dab409a766371ccdddd9ea4dadde7 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Fri, 19 Apr 2024 09:15:29 -0700 Subject: [PATCH 2/8] Fix typo (review feedback) Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index f429dbb4b1..7d1761ba25 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2350,7 +2350,7 @@ When used, the `discriminator` indicates the name of the property that hints whi Implementations MAY support defining generic or template data structures using JSON Schema's dynamic referencing feature: -* `$dynamicAnchor` identifies set of possible schemas (including a default placeholder schema) to which a `$dynamicRef` can resolve +* `$dynamicAnchor` identifies a set of possible schemas (including a default placeholder schema) to which a `$dynamicRef` can resolve * `$dynamicRef` resolves to the first matching encountered on its path from the schema entry point to the reference, as described in the JSON Schema specification ###### XML Modeling From 1b0ce70c115285d8c0f862dc095c823d1e206135 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 20 Apr 2024 16:13:12 -0700 Subject: [PATCH 3/8] Review fixes from gregsdennis --- versions/3.1.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 7d1761ba25..8f0bbf657f 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2351,7 +2351,7 @@ When used, the `discriminator` indicates the name of the property that hints whi 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 encountered on its path from the schema entry point to the reference, as described in the JSON Schema specification +* `$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 ###### XML Modeling @@ -2767,7 +2767,7 @@ components: $id: fully_generic_array type: array items: - $dynamicRef: #generic-array + $dynamicRef: "#generic-array" $defs: allowAll: $dynamicAnchor: generic-array From f6c0406264fdbd726beff630711b3ee36c797fa6 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 22 Apr 2024 15:34:28 -0700 Subject: [PATCH 4/8] Link to more info on dynamic refs for generics --- versions/3.1.1.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 8f0bbf657f..1b4abc31b1 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2353,6 +2353,8 @@ Implementations MAY support defining generic or template data structures using J * `$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. From 7b01059fbe4ca16c053e932ab8aba4a6656d4190 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 25 Apr 2024 06:08:14 -0700 Subject: [PATCH 5/8] Update versions/3.1.1.md Co-authored-by: Ralf Handl --- versions/3.1.1.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 1b4abc31b1..665c5ea75e 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2790,7 +2790,9 @@ components: objWithTypedArray: $id: obj_with_typed_array type: object - required: [dataType, data] + required: + - dataType + - data properties: dataType: enum: [string, number] From d847c3b30ff33bfe34c976c1a64c8ec2c229e0a7 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 25 Apr 2024 06:08:20 -0700 Subject: [PATCH 6/8] Update versions/3.1.1.md Co-authored-by: Ralf Handl --- versions/3.1.1.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 665c5ea75e..86b451f491 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2795,7 +2795,9 @@ components: - data properties: dataType: - enum: [string, number] + enum: + - string + - number oneOf: - properties: dataType: {const: string} From 333c51f16847e98739b0e71c39226f7aabe7ab2b Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 25 Apr 2024 06:08:38 -0700 Subject: [PATCH 7/8] Update versions/3.1.1.md Co-authored-by: Ralf Handl --- versions/3.1.1.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 86b451f491..2200b5ce89 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2800,11 +2800,15 @@ components: - number oneOf: - properties: - dataType: {const: string} - data: {$ref: array_of_strings} + dataType: + const: string + data: + $ref: array_of_strings - properties: - dataType: {const: number} - data: {$ref: array_of_numbers} + dataType: + const: number + data: + $ref: array_of_numbers ``` #### Discriminator Object From ff9bbdbbeeb6d26d9e338219cbfb58ab74007c3b Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 25 Apr 2024 06:09:06 -0700 Subject: [PATCH 8/8] Update versions/3.1.1.md Co-authored-by: Ralf Handl --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 2200b5ce89..12d44ced39 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2765,7 +2765,7 @@ components: ```YAML components: schemas: - genericArray: + genericArrayComponent: $id: fully_generic_array type: array items: