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

ondrej-simon · 2024-06-17T06:10:01Z

ondrej-simon
Jun 17, 2024

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?

Answered by handrews

Jun 24, 2024

@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 (altho…

View full answer

handrews · 2024-06-17T15:59:52Z

handrews
Jun 17, 2024
Collaborator

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

6 replies

handrews Jun 19, 2024
Collaborator

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 Jun 19, 2024
Author

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 Jun 19, 2024
Collaborator

@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 Jun 19, 2024
Collaborator

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 Jun 24, 2024
Author

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 · 2024-06-24T14:23:17Z

handrews
Jun 24, 2024
Collaborator

@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

1 reply

ondrej-simon Jun 24, 2024
Author

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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

{{title}}

Replies: 2 comments 7 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

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

ondrej-simon Jun 17, 2024

Scenario 1 - no mapping specified

Replies: 2 comments · 7 replies

handrews Jun 17, 2024 Collaborator

handrews Jun 19, 2024 Collaborator

ondrej-simon Jun 19, 2024 Author

handrews Jun 19, 2024 Collaborator

handrews Jun 19, 2024 Collaborator

ondrej-simon Jun 24, 2024 Author

Scenario 1 - no mapping specified

Schema definition

Execution matrix

Scenario 2 - partial mapping specified

Schema definition

Execution matrix

Scenario 3 - exhaustive mapping specified

Schema definition

Execution matrix

handrews Jun 24, 2024 Collaborator

Scenario 1 - no mapping specified

Scenario 2 - partial mapping specified

Schema definition

Execution matrix

Scenario 3 - exhaustive mapping specified

Schema definition

Execution matrix

ondrej-simon Jun 24, 2024 Author

ondrej-simon
Jun 17, 2024

Replies: 2 comments 7 replies

handrews
Jun 17, 2024
Collaborator

handrews Jun 19, 2024
Collaborator

ondrej-simon Jun 19, 2024
Author

handrews Jun 19, 2024
Collaborator

handrews Jun 19, 2024
Collaborator

ondrej-simon Jun 24, 2024
Author

handrews
Jun 24, 2024
Collaborator

ondrej-simon Jun 24, 2024
Author