Allow discriminator to be optional

[mikekistler]

This PR changes the discriminator to allow the discriminator property to be an optional field, so that when it is not present the default field can be used to specify which schema of the anyOf or oneOf is expected to validate the structure of the model.

I've also massaged the descriptions of polymorphism to emphasize that JSON Schema can and should be used to describe polymorphism and that discriminator is an optional extension of that support.

I also dropped some of the JSON examples when the same example was shown in yaml just to cut down on redundancy.

Tick one of the following options:

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[jeremyfiel]

I'm not totally on board with the naming of default.

The definition is different from JSON Schema and what you are trying to accomplish here by specifying a schema instance to validate against vs the commonly, well used, instance value.

src: https://json-schema.org/draft/2020-12/json-schema-validation#section-9.2

There are no restrictions placed on the value of this keyword. When multiple occurrences of this keyword are applicable to a single sub-instance, implementations SHOULD remove duplicates.

This keyword can be used to supply a default JSON value associated with a particular schema. It is RECOMMENDED that a default value be valid against the associated schema.

The other concern I have is the referenced schemas in oneOf/anyOf may have all properties optional, there is no requirement to have at least one required property to satisfy a oneOf subschema. The only requirement is that the validation succeeds which can be accomplished with other means besides a property name.

[handrews]

@jeremyfiel default could instead be ifAbsent or whenAbsent or something like that

[jeremyfiel]

a few minor edits for clarification

[jeremyfiel]

I feel like this line should be updated with the language of discriminating value

This was not part of your changes, but it's related and the perfect time to make additional clarifications

OpenAPI-Specification/src/oas.md

Line 3459 in 7ebde14

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:

[jeremyfiel]

This may be overkill to link all of the anchors, but I think that's how the spec usually does it. Feel free to ignore

There is one typo with the defaultMapping naming that should be corrected if you choose to ignore the anchor links.

[handrews]

As problematic as the allOf form is, I'm not sure I'm OK with removing the example entirely. People do use it, and we can't remove it in a minor version, and it's extremely hard to understand even with an example.

[handrews]

The name defaultMapping suggests to me that this is the default whenever there isn't a defined mapping. So not just when the property is missing, but when the property has a value that cannot otherwise be resolved. Is this the intention? If not, I'd suggest a name tying to absence rather than "default."

[mikekistler]

That was not the intention. But it is an interesting idea. This could be accomplished with a slightly different schema for the defaultMapping. Instead of not: required: ['petType'] it could be:

    properties:
      petType:
        not:
          enum: ['dog', 'cat']

This might get unwieldy for a schema with many variants, but there is some attractiveness to this.

Thoughts?

[mikekistler]

I pushed some commits that address most of the outstanding comments.

I made musts and mays uppercase. I added the language @handrews suggested about how discriminating values are used for allOf polymorphism. And I added back the example of polymorphism with allOf. It is a fair point that this pattern is confusing even with the example, so dropping it would only make matters worse.

I fixed the instance where default should have been defaultMapping -- thanks @jeremyfiel for catching this.

I did not make every instance of "Discriminator Object" into a link. When there were multiple occurrences of Discriminator Object in a section, I made the first one a link and left the rest as plain text. I think other "Object" types are handled similarly -- for example only 13 of the 20 occurrences of "Path Item Object" are links, the rest are plain text.

I left open the question about the name defaultMapping and whether we should let this apply when there is no other matching mapping element. Curious for folks opinions on this.

[ralfhandl]

Suggested change

which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The [Discriminator Object](#discriminator-object) cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:

which means a valid payload has to match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` can be used as a "hint" to improve the efficiency of selection of the matching schema. The [Discriminator Object](#discriminator-object) cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:

[ralfhandl]

Avoid "MUST" and "MAY" in Examples section

[ralfhandl]

Suggested change

	In scenarios where the value of the discriminating property does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used:
	In scenarios where the value of the discriminating property does not match the schema name or implicit mapping is not possible, an optional `mapping` definition can be used:

[ralfhandl]

Suggested change

	When the discriminating property is defined as optional, the Discriminator Object 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.
	When the discriminating property is defined as optional, the Discriminator Object has to 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.