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.

[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.

[ondrej-simon]

Hi Henry, I thought I understood it and then your last message confused me once again. :D I think it will be better with practical examples.

Given the following scenarios and execution matrices, is my understanding of discriminator and mapping correct, or not? If not, could you please clarify through a practical example where I am making an error? Thanks a lot for your time!

Scenario 1 - no mapping specified

Schema definition

Foo:
  type: object
  discriminator:
    propertyName: type
  required:
    - type
  properties:
    type:
      type: string
Bar:
  type: object
  allOf:
    - $ref: '#/components/schemas/Foo'
Baz:
  type: object
  allOf:
    - $ref: '#/components/schemas/Foo'

Execution matrix

type attribute value in input JSON	Result
Empty	❌ - the type attribute is required
Bar	✅ - maps to Bar object thanks to implicit mapping
Baz	✅ - maps to Baz object thanks to implicit mapping
bar	❌ - no mapping exists, only implicit Bar (capital B) is supported
baz	❌ - no mapping exists, only implicit Baz (capital B) is supported
BAR	❌ - no mapping exists, only implicit Bar is supported
BAZ	❌ - no mapping exists, only implicit Baz is supported

Scenario 2 - partial mapping specified

Schema definition

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

Execution matrix

type attribute value in input JSON	Result
Empty	❌ - the type attribute is required
Bar	❌ - implicit mapping is no longer supported, because explicit mapping exists
Baz	✅ - maps to Baz object thanks to implicit mapping
bar	❌ - no mapping exists, only explicit BAR is supported
baz	❌ - no mapping exists, only implicit Baz (capital B) is supported
BAR	✅ - maps to Bar object thanks to explicit mapping
BAZ	❌ - no mapping exists, only implicit Baz is supported

Scenario 3 - exhaustive mapping specified

Schema definition

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

Execution matrix

type attribute value in input JSON	Result
Empty	❌ - the type attribute is required
Bar	❌ - implicit mapping is no longer supported, because explicit mapping exists
Baz	❌ - implicit mapping is no longer supported, because explicit mapping exists
bar	❌ - no mapping exists, only explicit BAR is supported
baz	❌ - no mapping exists, only explicit BAZ is supported
BAR	✅ - maps to Bar object thanks to explicit mapping
BAZ	✅ - maps to Baz object thanks to explicit mapping

[handrews]

@ondrej-simon I think you're making this more complicated than it is. The algorithm is very simple:

• If there is an explicit mapping for the exact, case-sensitive value, then use the explicit mapping
• Otherwise, if there is an implicit mapping for the exact, case-sensitive value, then use the implicit mapping
• If neither exists, fail

There are no other checks involved. There's nothing that "masks" based on differences in case. There's nothing preventing multiple values from mapping (implicitly or explicitly) to the same schema. It's just those two steps, nothing else.

I've adjusted your scenarios accordingly:

Scenario 1 - no mapping specified

This scenario is correct as you wrote it (although I'd make similar phrasing changes to the "Result" column as in the next two scenarios.

Scenario 2 - partial mapping specified

Schema definition

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

Execution matrix

type attribute value in input JSON	Result
Empty	❌ - the type attribute is required
Bar	✅ - implicit mapping because matching is case-sensitive
Baz	✅ - maps to Baz object thanks to implicit mapping
bar	❌ - no mapping exists, no component name matches
baz	❌ - no mapping exists, no component name matches
BAR	✅ - maps to Bar object thanks to explicit mapping
BAZ	❌ - no mapping exists, only implicit Baz is supported

There is nothing in the Discriminator Object specification that prevents two values (Bar and BAR) from mapping to the same schema. Defining an explicit mapping for BAR doesn't have any impact on Bar (or bar, or bAr, etc.).

Scenario 3 - exhaustive mapping specified

Schema definition

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

Execution matrix

type attribute value in input JSON	Result
Empty	❌ - the type attribute is required
Bar	✅ - implicit mapping because matching is case-sensitive
Baz	✅ - implicit mapping because matching is case-sensitive
bar	❌ - no mapping exists, no component name matches
baz	❌ - no mapping exists, no component name matches
BAR	✅ - maps to Bar object thanks to explicit mapping
BAZ	✅ - maps to Baz object thanks to explicit mapping

[ondrej-simon]

Perfect, Henry, thank you, this is exactly what I needed to see - the implicit mapping stays and is supported even when explicit one is present.

Thank you for your patience.

[handrews]

Closing as answered