As per OAS, when defining discriminator with explicit mapping, should implicit discriminator value still be accepted?

[ondrej-simon]

Hi, I have not found any information about this in the documentation (potential hint for extension), so I am asking here.

Let's say I have the following schema which explicitly defines mapping for Bar and Baz objects:

Foo:
  type: object
  discriminator:
    propertyName: type
    mapping:
      BAR: '#/components/schemas/Bar'
      BAZ: '#/components/schemas/Baz'
  required:
    - type
  properties:
    type:
      type: string

I know that when a discriminator is not present, an implicit mapping is to be considered to aid (de)serialization, in this case type: Bar would map to Bar, and type: Baz would map to Baz.

But when I define explicit mapping, should the implicit value still be allowed, or should the API accept only the manually specified options?

[handrews]

@ondrej-simon mapping does not prevent implicit mappings from working:

If the discriminator value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail.

The last example given in the Discriminator Object section actually illustrates this - "Cat" is handled through an implicit mapping, while "dog" is done with an explicit value in mapping.

[ondrej-simon]

Hi @handrews, I get that "Cat" (the implicit mapping for Cat object) still must work, but in the example, should both "dog" (explicit) and "Dog" (implicit, not present) work? Or should only "dog" be allowed?

Thank you for the reply.

[handrews]

The regular 2020-12 JSON Schema keywords are what determines whether an instance is valid according to the schema. So as long as both dog and Dog are valid, then they should be treated separately. There is no case-folding involved that would make them be treated as a special single unit. They're just as different as Dog and Cat (or perhaps Dog and Fog would be closer).

[ondrej-simon]

So to summarize, when I specify an explicit mapping for Dog, be it "dog", "dog", "DOG" or "whatever", the implicit "Dog" value should no longer be supported, because it is overriden by the explicit specification.

This is the information I was missing from the documentation. Without this explanation, it seemed that when I define e.g. "fog" to map to Dog, the implicit "Dog" mapping would still work. But this is actually not the case.

[handrews]

@ondrej-simon no, I must not have written things clearly. Every possible value is distinct, and handled independently. There is nothing that recognizes "dog", "Dog", "DOG", etc. as being related. They are distinct UTF-8 strings, with no case-folding (case-folding is how UTF-8 implements case-insensitivity). Nothing you do with one value has anything to do with any of the other values.

[handrews]

As for wording in the specification, this falls under the general guidance that fields are case-sensitive unless specified otherewise. That includes the Components Objects names that are used for implicit mapping.