From cda2ba7d6dda8e339a9b1de33391c14e7d844a6e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 19 May 2024 11:42:51 -0700 Subject: [PATCH 1/2] Clarify discriminator + oneOf/anyOf/allOf usage (3.2.0) This moves some guidance up to the fixed fields section where it is more obvious, and explicitly designates other configurations as having undefined behavior. It also creates subsections to organize the different topics, pulls key guidance out of the examples and up into those sections, and provides clarification on the ambiguity of names and URIs. Finally, it incorporates ideas from @jdesrosiers regarding the ambiguous `mapping` syntax submitted in a prior PR, but does so in a way that meets our compatibility requirements for patch releases. For the same compatibility reasons, the MUST wording for requiring the named discriminator property in the schema was (regrettably) weakened to a "SHOULD but otherwise undefined", as we have done for other problematic ambiguities. Co-authored-by: Jason Desrosiers --- versions/3.2.0.md | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index 4c1b95eaf0..d0a5fff5fd 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -153,6 +153,10 @@ An OpenAPI document MAY be made up of a single document or be divided into multi It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`. +#### Resolving Implicit Connections + +***TODO: In another PR*** + ### Data Types Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). @@ -2887,19 +2891,38 @@ components: #### 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. - -When using the discriminator, _inline_ schemas will not be considered. +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. +This hint can be used to aid in serialization, deserialization, and validation. +The Discriminator Object does this by implicitly or explicitly associating the possible values of a named property with alternative schemas. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. - mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or references. +propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. This property SHOULD be required in the payload schema, as the behavior when the property is absent is undefined. + mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or URI references. This object MAY be extended with [Specification Extensions](#specificationExtensions). -The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. Note that because the discriminating property's value is used as a component name and/or as the key in the `mapping` object, the behavior of any value that is not a string is undefined. +##### Conditions for Using the Discriminator Object +The Discriminator Object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. +In both the `oneOf` and `anyOf` use cases, where those keywords are adjacent to `discriminator`, all possible schemas MUST be listed explicitly. +To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas building on the parent schema via an `allOf` construct may be used as an alternate schema. + +The behavior of any configuration of `oneOf`, `anyOf`, `allOf` and `discriminator` that is not described above is undefined. + +##### Options for Mapping Values to Schemas +The value of the property named in `propertyName` is used as the name of the associated schema under the [Components Object](#componentsObject), _unless_ a `mapping` is present for that value. +The `mapping` entry maps a specific property value to either a different schema component name, or to a schema identified by a URI. +When using implicit or explicit schema component names, inline `oneOf` or `anyOf` subschemas are not considered. +The behavior of a `mapping` value that is both a valid schema name and a valid relative URI reference is implementation-defined, but it is RECOMMENDED that it be treated as a schema name. +To ensure that an ambiguous value (e.g. `"foo"`) is treated as a relative URI reference by all implementations, authors MUST prefix it with the `"."` path segment (e.g. `"./foo"`). + +Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. +However, the exact nature of such conversions are implementation-defined. + +##### Examples + +For these examples, assume all schemas are in the entry OpenAPI document; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolvingImplicitConnections). In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: @@ -2951,13 +2974,11 @@ MyResponseType: monster: https://gigantic-server.com/schemas/Monster/schema.json ``` -Here the discriminator _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `Dog`. If the discriminator _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison. +Here the discriminator property _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`. If the discriminator property _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload. -In both the `oneOf` and `anyOf` use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an `allOf` construct may be used as an alternate schema. - -For example: +This example shows the `allOf` usage, which avoids needing to reference all child schemas in the parent: ```yaml components: From cccd70bffaaedd1534d41fe9b12dde292cfc9df2 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 31 May 2024 13:57:02 -0700 Subject: [PATCH 2/2] Use "discriminating value" consistently I found the "discriminator value" language confusing, because `discriminator` is the field name, and in most cases the value of a field is the value in the OpenAPI Description. Reviewers did not like "discriminator property value", but "discriminating value" makes it clear that this is about the value that actually causes schema selection, and not about the value of the discriminator keyword. Also removed placeholder in favor of just having the headings, as has been done in several other PRs that overlap with new section PRs for internal linking. --- versions/3.2.0.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/versions/3.2.0.md b/versions/3.2.0.md index d0a5fff5fd..6eedfeefce 100644 --- a/versions/3.2.0.md +++ b/versions/3.2.0.md @@ -155,8 +155,6 @@ It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `op #### Resolving Implicit Connections -***TODO: In another PR*** - ### Data Types Data types in the OAS are based on the types supported by the [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-4.2.1). @@ -2675,7 +2673,7 @@ components: ] }, "Cat": { - "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.", + "description": "A representation of a cat. Note that `Cat` will be used as the discriminating value.", "allOf": [ { "$ref": "#/components/schemas/Pet" @@ -2702,7 +2700,7 @@ components: ] }, "Dog": { - "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.", + "description": "A representation of a dog. Note that `Dog` will be used as the discriminating value.", "allOf": [ { "$ref": "#/components/schemas/Pet" @@ -2744,7 +2742,7 @@ components: required: - name - petType - Cat: # "Cat" will be used as the discriminator value + Cat: # "Cat" will be used as the discriminating value description: A representation of a cat allOf: - $ref: '#/components/schemas/Pet' @@ -2760,7 +2758,7 @@ components: - aggressive required: - huntingSkill - Dog: # "Dog" will be used as the discriminator value + Dog: # "Dog" will be used as the discriminating value description: A representation of a dog allOf: - $ref: '#/components/schemas/Pet' @@ -2898,7 +2896,7 @@ The Discriminator Object does this by implicitly or explicitly associating the p ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminator value. This property SHOULD be required in the payload schema, as the behavior when the property is absent is undefined. +propertyName | `string` | **REQUIRED**. The name of the property in the payload that will hold the discriminating value. This property SHOULD be required in the payload schema, as the behavior when the property is absent is undefined. mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or URI references. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2974,7 +2972,7 @@ MyResponseType: monster: https://gigantic-server.com/schemas/Monster/schema.json ``` -Here the discriminator property _value_ of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`. If the discriminator property _value_ does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. +Here the discriminating value of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`. If the discriminating value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.