diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e4423df5b2..12d44ced39 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -2346,6 +2346,15 @@ 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 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. @@ -2689,6 +2698,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 +``` + #### 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.