Skip to content

Commit

Permalink
Use defaultMapping keyword in discriminator
Browse files Browse the repository at this point in the history
  • Loading branch information
mikekistler committed Feb 11, 2025
1 parent 9faf031 commit 7ebde14
Showing 1 changed file with 8 additions and 8 deletions.
16 changes: 8 additions & 8 deletions src/oas.md
Original file line number Diff line number Diff line change
Expand Up @@ -2877,7 +2877,7 @@ These keywords can be used to describe polymorphism, where a single field can ac

The OpenAPI specification extends the JSON Schema support for polymorphism by adding the [`discriminator`](#schema-discriminator) field.
When used, the `discriminator` indicates the name of the property that hints which schema of an `anyOf` or `oneOf` is expected to validate the structure of the model.
The discriminating property may be defined as required or optional, but when defined as an optional property the `discriminator` field must include a `default` field that specifies which schema of the `anyOf` or `oneOf` is expected to validate the structure of the model.
The discriminating property may be defined as required or optional, but when defined as an optional property the `discriminator` field must include a `defaultMapping` field that specifies which schema of the `anyOf` or `oneOf` is expected to validate the structure of the model when the discriminating property is not present.

There are two ways to define the value of a discriminator for an inheriting instance.

Expand Down Expand Up @@ -3372,9 +3372,9 @@ Note that `discriminator` MUST NOT change the validation outcome of the schema.

| Field Name | Type | Description |
| ---- | :----: | ---- |
| <a name="property-name"></a>propertyName | `string` | **REQUIRED**. The name of the discriminating property in the payload that will hold the discriminating value. The discriminating property may be defined as required or optional, but when defined as optional the `discriminator` field must include a `default` field that specifies which schema is expected to validate the structure of the model. |
| <a name="property-name"></a>propertyName | `string` | **REQUIRED**. The name of the discriminating property in the payload that will hold the discriminating value. The discriminating property may be defined as required or optional, but when defined as optional the `discriminator` field must include a `defaultMapping` field that specifies which schema is expected to validate the structure of the model when no discriminating property is present. |
| <a name="discriminator-mapping"></a> mapping | Map[`string`, `string`] | An object to hold mappings between payload values and schema names or URI references. |
| <a name="default"></a> default | `string` | The schema name or URI reference to a schema that is expected to validate the structure of the model when the discriminating property is not present in the payload. |
| <a name="default"></a> defaultMapping | `string` | The schema name or URI reference to a schema that is expected to validate the structure of the model when the discriminating property is not present in the payload. |

This object MAY be extended with [Specification Extensions](#specification-extensions).

Expand Down Expand Up @@ -3404,11 +3404,11 @@ However, the exact nature of such conversions are implementation-defined.

##### Optional discriminating property

When the discriminating property is defined as optional, the `discriminator` field must include a `default` field that specifies a schema that is expected to validate the structure of the model when the discriminating property is not present in the payload. This allows the schema to still be validated correctly even if the discriminator property is missing.
When the discriminating property is defined as optional, the `discriminator` field must include a `defaultMapping` field that specifies a schema that is expected to validate the structure of the model when the discriminating property is not present in the payload. This allows the schema to still be validated correctly even if the discriminator property is missing.

The primary use case for an optional discriminating property is to allow a schema to be extended with a discriminator without breaking existing clients that do not provide the discriminating property.

Typically the schema specified in the `default` field will specify that the discriminating property is not present, e.g.
Typically the schema specified in the `defaultMapping` field will specify that the discriminating property is not present, e.g.

```yaml
OtherPet:
Expand All @@ -3417,7 +3417,7 @@ OtherPet:
required: ['petType']
```

This will prevent the default schema from validating a payload that includes the discriminating property, which would cause a validation of the payload to fail when polymorphism is described using the `oneOf` JSON schema keyword.
This will prevent the default mapping schema from validating a payload that includes the discriminating property, which would cause a validation of the payload to fail when polymorphism is described using the `oneOf` JSON schema keyword.

##### Examples

Expand Down Expand Up @@ -3476,7 +3476,7 @@ Here the discriminating value of `dog` will map to the schema `#/components/sche

When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity for serializers/deserializers where multiple schemas may satisfy a single payload.

When the discriminating property is defined as optional, the `discriminator` field must include a `default` field that specifies a schema of the `anyOf` or `oneOf` is expected to validate the structure of the model when the discriminating property is not present in the payload. This allows the schema to still be validated correctly even if the discriminator property is missing.
When the discriminating property is defined as optional, the `discriminator` field must include a `defaultMapping` field that specifies a schema of the `anyOf` or `oneOf` is expected to validate the structure of the model when the discriminating property is not present in the payload. This allows the schema to still be validated correctly even if the discriminator property is missing.

For example:

Expand All @@ -3489,7 +3489,7 @@ MyResponseType:
- $ref: '#/components/schemas/OtherPet'
discriminator:
propertyName: petType
default: OtherPet
defaultMapping: OtherPet
OtherPet:
type: object
not:
Expand Down

0 comments on commit 7ebde14

Please sign in to comment.