From 343b5e847c8e03799ef22d69b46622fc32d95591 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 16:41:03 +0000 Subject: [PATCH 01/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index ac68e58d8d..6cbfa4400f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2689,10 +2689,10 @@ This object MAY be extended with [Specification Extensions](#specificationExtens The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. -In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: +A payload MAY be described to be exactly one of any number of types: ```yaml -MyResponseType: +MyType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' @@ -2703,7 +2703,7 @@ which means the payload _MUST_, by validation, match exactly one of the schemas ```yaml -MyResponseType: +MyType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' @@ -2712,7 +2712,7 @@ MyResponseType: propertyName: petType ``` -The expectation now is that a property with name `petType` _MUST_ be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the response payload: +The expectation now is that a property with name `petType` _MUST_ be present in the payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the payload: ```json { @@ -2726,7 +2726,7 @@ Will indicate that the `Cat` schema be used in conjunction with this payload. In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used: ```yaml -MyResponseType: +MyType: oneOf: - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' From 0e8a0776713007211aaad351345a87a149861187 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 16:52:23 +0000 Subject: [PATCH 02/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 6cbfa4400f..1ab89beb67 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2334,7 +2334,6 @@ The OpenAPI Specification allows combining and extending model definitions using While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, the OpenAPI Specification adds the `discriminator` field. When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model. -As such, the `discriminator` field MUST be a required field. There are two ways to define the value of a discriminator for an inheriting instance. - Use the schema name. - Override the schema name by overriding the property with a new value. If a new value exists, this takes precedence over the schema name. @@ -2687,6 +2686,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). +The discriminator `propertyName` field MUST be a required field in the schema object. The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. A payload MAY be described to be exactly one of any number of types: From 2efae8d4188050aa4873e7e534f16ef9cfd81615 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 17:11:14 +0000 Subject: [PATCH 03/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 1ab89beb67..152a36dbdb 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2674,9 +2674,14 @@ 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 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. +A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. +The discriminator `propertyName` field MUST be a required field in the schema object. However, as shown below, the discriminator is not required to be present in the payload for _inline_ schemas. + +The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. The child schemas MAY be a mix of _inline_ or references schemas. +When a child schema is specified as a reference, the discriminator property _MUST_ be present in the payload. +When a child schema is specified _inline_, the discriminator property is not required in the payload. Validation is applied to determine if the payload matches the child JSON schema. ##### Fixed Fields Field Name | Type | Description @@ -2686,9 +2691,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -The discriminator `propertyName` field MUST be a required field in the schema object. -The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. - A payload MAY be described to be exactly one of any number of types: ```yaml @@ -2699,7 +2701,7 @@ MyType: - $ref: '#/components/schemas/Lizard' ``` -which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use: +which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. We can then describe exactly which field tells us which schema to use: ```yaml @@ -2712,7 +2714,7 @@ MyType: propertyName: petType ``` -The expectation now is that a property with name `petType` _MUST_ be present in the payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the payload: +The expectation now is that a property with name `petType` _MUST_ be present in the payload, and the value will correspond to the name of a schema defined in the OAS document. Thus the payload: ```json { From 591bf43469922506c5e2068da4d6c3c69987c867 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 21:34:42 +0000 Subject: [PATCH 04/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 152a36dbdb..3848b8e21b 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2674,7 +2674,7 @@ 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 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. A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. The discriminator `propertyName` field MUST be a required field in the schema object. However, as shown below, the discriminator is not required to be present in the payload for _inline_ schemas. From 9d4acf1e29b0747823bb7b5cce42d23794298975 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 21:37:43 +0000 Subject: [PATCH 05/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 3848b8e21b..088c8dc732 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2691,6 +2691,8 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). +##### Discriminator Object Example + A payload MAY be described to be exactly one of any number of types: ```yaml From 47dd48ada0cdd244e669e0010ca3f42e66062d41 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 22:04:41 +0000 Subject: [PATCH 06/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 088c8dc732..2ac1910e1d 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2676,12 +2676,12 @@ components: 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. -A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. +The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. Both _inline_ and references are valid child schemas. +When a child schema is a reference, the discriminator property _MUST_ be present in the payload. A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. Even when the discriminator is used as shortcut hint, the payload MUST still be validated against the JSON schema. +When a child schema is specified _inline_, the discriminator property is not required in the payload. Validation is applied to determine if the payload matches the child JSON schema. + The discriminator `propertyName` field MUST be a required field in the schema object. However, as shown below, the discriminator is not required to be present in the payload for _inline_ schemas. -The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. The child schemas MAY be a mix of _inline_ or references schemas. -When a child schema is specified as a reference, the discriminator property _MUST_ be present in the payload. -When a child schema is specified _inline_, the discriminator property is not required in the payload. Validation is applied to determine if the payload matches the child JSON schema. ##### Fixed Fields Field Name | Type | Description From fd5c9e3aa347877fa3cf01e83a5efea10a596bef Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 22:05:11 +0000 Subject: [PATCH 07/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 2ac1910e1d..db6c59015f 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2698,6 +2698,7 @@ A payload MAY be described to be exactly one of any number of types: ```yaml MyType: oneOf: + - type: 'null' - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' @@ -2709,6 +2710,7 @@ which means the payload _MUST_, by validation, match exactly one of the schemas ```yaml MyType: oneOf: + - type: 'null' - $ref: '#/components/schemas/Cat' - $ref: '#/components/schemas/Dog' - $ref: '#/components/schemas/Lizard' From fa38c08c226b7858a0ea93fc56152a35543b2179 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 22:06:39 +0000 Subject: [PATCH 08/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index db6c59015f..29b193ec99 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2677,7 +2677,9 @@ components: 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. The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. Both _inline_ and references are valid child schemas. -When a child schema is a reference, the discriminator property _MUST_ be present in the payload. A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. Even when the discriminator is used as shortcut hint, the payload MUST still be validated against the JSON schema. +When a child schema is a reference, the discriminator property _MUST_ be present in the payload. +A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. +Even when the discriminator is used as shortcut hint, the payload MUST still be validated against the JSON schema. When a child schema is specified _inline_, the discriminator property is not required in the payload. Validation is applied to determine if the payload matches the child JSON schema. The discriminator `propertyName` field MUST be a required field in the schema object. However, as shown below, the discriminator is not required to be present in the payload for _inline_ schemas. From 501b829c51a2d88801a7b8c1e58159853e7e0565 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Sun, 26 Apr 2020 22:14:31 +0000 Subject: [PATCH 09/10] Improve OAS spec for discriminator --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 29b193ec99..28533137d2 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2680,7 +2680,7 @@ The discriminator object is legal only when using one of the composite keywords When a child schema is a reference, the discriminator property _MUST_ be present in the payload. A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. Even when the discriminator is used as shortcut hint, the payload MUST still be validated against the JSON schema. -When a child schema is specified _inline_, the discriminator property is not required in the payload. Validation is applied to determine if the payload matches the child JSON schema. +When a child schema is specified _inline_, the discriminator property is not required to be present in the payload. Validation is applied to determine if the payload matches the child JSON schema. The discriminator `propertyName` field MUST be a required field in the schema object. However, as shown below, the discriminator is not required to be present in the payload for _inline_ schemas. From 3edee8d3269c719ac895b9849ab0b6e3b9ea48a3 Mon Sep 17 00:00:00 2001 From: "Sebastien Rosset (serosset)" Date: Thu, 30 Apr 2020 18:02:43 -0700 Subject: [PATCH 10/10] Change sentence to take Justin's feedback into consideration --- versions/3.1.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.0.md b/versions/3.1.0.md index 28533137d2..01331ac0fb 100644 --- a/versions/3.1.0.md +++ b/versions/3.1.0.md @@ -2676,7 +2676,7 @@ components: 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. -The discriminator object is legal only when using one of the composite keywords `oneOf`, `anyOf`, `allOf`. Both _inline_ and references are valid child schemas. +The discriminator object is legal only when using a schema that has one or more of the composite keywords `oneOf`, `anyOf`, `allOf`. Both _inline_ and references can be used as composite child schemas. When a child schema is a reference, the discriminator property _MUST_ be present in the payload. A discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. Even when the discriminator is used as shortcut hint, the payload MUST still be validated against the JSON schema.