Optional discriminator property

[mikekistler]

I propose that we change the discriminator object in the next appropriate spec version to allow the discriminator property (named by the propertyName filed) to be an optional property. When the discriminator property is absent, this is interpreted as mapping to an implicit variant of the oneOf/anyOf/allOf with an empty schema. (This might be problematic for oneOf).

This has been discussed in the past and I don't recall any strong objections to it.

Making the discriminator optional allows a more natural transition from a "monomorphic" schema (without a discriminator) to a polymorphic schema. In particular, objects that validate to the monomorphic schema (without a discriminator property) would continue to be valid in the polymorphic schema.

[LasneF]

as discriminator need to stand for 3.X , the only allowed is to releax constrains , so it could be ,
in the other hand one option would be to set in 3.2 that it is depreacted (but supported) targetting to drop it for 4.x

[mikekistler]

Discussed in the Jan 23 TDC meeting and next step is for me to add actual examples.

[handrews]

@mikekistler This proposal only allows for a missing property to map to an empty schema, never an explicit schema? I think I missed that earlier. That does make it easier- essentially, if we treat this as a class hierarchy, the missing property is intended to just use the base class, correct?

I'm not sure how this can work with either oneOf or anyOf, as in both cases you need to satisfy at at least one of the schemas. The only difference is whether it's also at most one, or if it can be more than one. But mapping to an implicit empty schema won't satisfy any of them (except by coincidence).

You can't even solve this by using anyOf and putting an explicit empty schema under it, because that would make the anyOf always pass, even if the discriminator points to a named schema against which the instance is invalid. Because discriminator is not allowed to change the validation outcome (to preserve JSON Schema compatibility).

---

The only scenario in which this might work is the allOf scenario, which seems to be unevenly supported. And I'm not entirely sure it works there either.

Actually, I'm still not sure the allOf approach is compatible with JSON Schema at all. If your endpoint references a child schema, then it will follow the allOf to the parent with the discriminator, but if the discriminator property value does not match the expected value for the child schema referenced by the end point, it will fail validation. You can't use this structure to dynamically switch to a different child schema.

If your endpoint references the parent schema that contains discriminator, now you can use whichever child schema matches, but standard JSON Schema won't validate the child schema at all, because the reference is in the wrong direction. Standard JSON Schema has no way to search other parts of a document - it only evaluates based on JSON Schema keywords.

I've never really pushed on this because there doesn't seem to be a solution, and it's not entirely clear to me how much the allOf form is used, but if we're going to try to extend the allOf option then it matters more that it doesn't entirely work in the first place.

[mikekistler]

@handrews

the missing property is intended to just use the base class, correct?

Yes

I'm not sure how this can work with either oneOf or anyOf, as in both cases you need to satisfy at at least one of the schemas.

In my proposal, I suggested that an optional discriminator property implicitly adds a variant to a oneOf or anyOf to represent the "base class" case. Karen E gave some suggestions on what such a variant schema would look like.

But mapping to an implicit empty schema won't satisfy any of them (except by coincidence).

Exactly. That is the intent. It shouldn't map to any of them.

But perhaps your objection is that the empty schema being "implicit" means that you can't just ignore the discriminator property -- treat it as a hint. Okay, I get that. So maybe we require a default field in the discriminator object when the discriminator property is optional and it maps to one of the variants, and that variant must be included in the oneOf / anyOf.

So maybe something like this:

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
        mapping:
          "Cat": #/components/schemas/Cat
          "Dog": #/components/schemas/Dog
        default: #/components/schemas/AnyPet
      properties:
        name:
          type: string
        petType:
          type: string
      required:
      - name
      oneOf:
      - $ref: #/components/schemas/Cat
      - $ref: #/components/schemas/Dog
      - $ref: #/components/schemas/AnyPet
    Cat:
      description: A representation of a cat
      type: object
      properties:
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - huntingSkill
    Dog:
      description: A representation of a dog
      type: object
      properties:
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - packSize
    AnyPet:
      description: Pet with unknown type
      not:
      - required: ["PetType"]

[handrews]

But perhaps your objection is that the empty schema being "implicit" means that you can't just ignore the discriminator property -- treat it as a hint.

Yeah, we went through a long debate and a lot of effort to ensure that discriminator does not impact JSON Schema validation in any way. I'm not willing to change that- it would cause an immense amount of problems and disruption in the tooling landscape. The whole point of 3.1 was to avoid needing specialized JSON Schema implementations, and given how hard-won that change has been I am not willing to revisit it at all.

Okay, I get that. So maybe we require a default field in the discriminator object when the discriminator property is optional and it maps to one of the variants, and that variant must be included in the oneOf / anyOf.

This might work, as it preserves the current behavior of anyOf/oneOf and the behavior of discriminator as an just an optimization (and therefore truly optional) as far as JSON Schema is concerned.

[mikekistler]

BTW, I wonder if we should de-emphasize the "allOf" discriminator pattern in the 3.2 (or later) spec, in favor of either "oneOf" or "anyOf". In particular, the only "complete" examples of polymorphism in the spec (there are two of them) currently uses the "allOf" pattern. I think we should be nudging folks away from this so changing these to either "allOf" or "anyOf" might be a good change.

[handrews]

The problem is that for some use cases, allOf makes more sense, and for some use cases, oneOf/anyOf makes more sense.

Actually, the fundamental problem is that the design of discriminator is completely in opposition to the entire JSON Schema evaluation process, and there will never be any solution to that problem. It's not salvageable. You can only make more and more complex, rickety, and unlikely-to-be-properly-supported band-aids.

[mikekistler]

Actually, the fundamental problem is that the design of discriminator is completely in opposition to the entire JSON Schema evaluation process, and there will never be any solution to that problem. It's not salvageable.

@handrews Please don't hold back ... you can say what you really think. ;-)

The difference that I see between the "allOf" and "oneOf"/"anyOf" patterns is that in the "allOf" pattern, the discriminator object conveys meaning that is not represented in the JSON schema -- that "Pet" (for example) represents a schema with "variants" -- but this is clearly represented in the JSON Schema in the "oneOf" / "anyOf" patterns. At least I think this is true but happy to be corrected if I'm mistaken.

[handrews]

in the "allOf" pattern, the discriminator object conveys meaning that is not represented in the JSON schema -- that "Pet" (for example) represents a schema with "variants"

Yes, that's the problem

but this is clearly represented in the JSON Schema in the "oneOf" / "anyOf" patterns

Yes, those work, although the 'magic" name-matching behavior of discriminator is still outside of JSON Schema (which is why it's so important ot ensure that it does not require additional non-JSON Schema behavior, at least for the oneOf/anyOf patterns).

Underlying this is the fact that, from a data definition perspective, the allOf approach is correct, but from a data validation perspective, the oneOf/anyOf approach is correct. This tension is present throughout the OAS's use of JSON Schema, but discriminator makes it explicit, real, and (in the case of the allOf pattern) un-solvable within JSON Schema validation.

[handrews]

Anyway, none of the above is relevant to whether adding a default field to the Discriminator Object will work. It should work as well (oneOf/anyOf) or poorly (allOf) as discriminator currently works.