OAS Dialect does not require the OAS vocabulary

[jam01]

Schema Object#Properties states that

The OpenAPI Schema Object dialect is defined as requiring the OAS base vocabulary ...

yet the dialect schema does not require that vocab:

https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/dialect/base.schema.json#L16C57-L16C62

[handrews]

The false for the vocab in $vocabulary means that the vocabulary does not directly impact validation (discriminator can optimize validation performance, but does not change the outcome). So an implementation that does not understand that vocabulary can safely process the schema anyway, unlike if it doesn't understand a vocabulary that is required with true.

So the dialect schema is correct, it's just that the meaning of true and false has to do with validation rather than overall usage.

[karenetheridge]

The base dialect does actually "include" that vocabulary: it's at https://github.com/OAI/OpenAPI-Specification/blob/main/schemas/v3.1/dialect/base.schema.json#L23 (this is where the definitions of xml, discriminator etc are pulled in). This will ensure that if someone does use those keywords in their schema openapi document, that their use is syntactically correct; whether or not an implementation actually understands and processes that vocabulary is left as optional, as Henry described above with the use of false in the vocabulary declaration.

[jam01]

Thank you both for your responses.

However my understanding is that discriminator is only a performance hint when used in conjunction with all/any/oneOf. But given the example from the spec:

Scenario 1

components:
  schemas:
    Pet:
      type: object
      required:
      - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Cat`
    Dog:
      allOf:
      - $ref: '#/components/schemas/Pet'
      - type: object
        # all other properties specific to a `Dog`

a plain 2020-12 validator validating against Pet wouldn't know to apply any of the Cat or Dog as expected, unless it understands discriminator. So the outcome is changed.

Or am I misunderstanding how discriminator works? 🙃

[jam01]

And actually, even in the case of all/any/oneOf the result might be different, no?

Scenario 2

MyResponseType:
  allOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  discriminator:
    propertyName: petType

{ "petType": "Fish" }

allOf could reference some schemas Cat and Dog but the discriminator value could be Fish. This scenario would require that allOf[Cat, Dog] && Fish are validated, meaning a different outcome than a plain 2020-12 validator.

Currently the specification only mandates listing all possible schemas explicitly for oneOf and anyOf.

Scenario 3

MyResponseType:
  oneOf:
  - $ref: '#/components/schemas/Fish'
  - $ref: '#/components/schemas/Dog' # {"properties": { "bark": true }}
  discriminator:
    propertyName: petType

{ "petType": "Fish", "bark": "woof" }

In oneOf and anyOf where the references must be exhaustive, the payload may still validate against, say, Dog but the discriminator value may be Fish. This scenario would require that oneOf[Fish, Dog] && Fish are validated, meaning a different outcome than a plain 2020-12 validator which may validate against Dog only.

[handrews]

discriminator has always been.. difficult. The following issue records that the TSC decided that discriminator cannot change the validation outcome:

• Discriminators (not) changing the JSON Schema Validator behavior #2516

I looked up the TSC agenda issue for that week but it does not elaborate (we've since gotten better about explaining decisions, but unless it's still possible to dig up old recordings, there's no way to look back at that one- I wasn't around at the time so I don't recall the details).

Of course, as with many things in JSON Schema, it's possible to write things that don't work the way you'd want the to.

This scenario would require that oneOf[Fish, Dog] && Fish are validated, meaning a different outcome than a plain 2020-12 validator which may validate against Dog only.

The correct behavior in this case is the JSON Schema behavior. discriminator cannot contradict oneOf or anyOf. It can't optimize oneOf because you have to check every branch before you can determine the outcome. It can only optimize anyOf if you're not using annotations and aren't using any keywords (like unevaluatedProperties) that depend on annotations.

This has been clarified for the forthcoming 3.1.1 and 3.0.4 releases- see PR #2618 and #3846.

Or am I misunderstanding how discriminator works? 🙃

The allOf use case of discriminator is weird, and maybe there's one more clarification to slip into the patch releases here.

For validation purposes, if you validate using the Pet schema, then you just validate against Pet, and not against any other schema. In this usage, discriminator only really helps with things like code generation and data de-serialization. It doesn't help with validation.

I'll re-open while deciding if there's anything more to do to improve the wording.

[jam01]

Thanks @handrews . I gotta say json-schema and OAS set the standard for community driven projects on decision making and documenting mechanisms.

I started digging into the links you shared (and their own links) which might take a minute. But I'm clear now on the expected functionality.

My question arises from a new json-schema implementation in Scala that I'm soon completing, and wanted to look into OAS support. Given the nature of my implementation and now understanding that discriminator does not affect validation, I'll abandon its support.

I originally understood discriminator to be like what dependentSchemas is except at run-time vs schema design-time. The run-time behavior still feels valuable though... 🤔