Understanding references to polymorphic types with "allOf" and "discriminator"

[mhonert]

Hi everyone,

I have a question about the Pet, Cat, and Dog polymorphism example using "allOf" and "discriminator" from the OpenAPI specification. There have been several discussions and issues in the past about this topic, but I could not find an answer to this specific question.

A short summary of the example:
The "Pet" schema object defines properties common to all pets. The "Dog" and "Cat" schemas use "allOf" to combine all pet properties with properties specific to a "Dog" or "Cat".

The "Pet" schema also contains the "discriminator" object, which according to the specification, "can be used to aid in serialization, deserialization, and validation."

What I could not find information about is what this means when another schema object references the "Pet" within one of its properties, like in this example:

PetStore:
  type: object
  properties:
    availablePets:
      type: array
      items:
        $ref: '#/components/schemas/Pet'

If the "discriminator" object is just an "aid" and does not change the semantics of allOf, then I would expect that simply referencing the 'Pet' schema object here is not sufficient if the goal is to allow only valid "Cat" or "Dog" objects as values for 'availablePets'.

With the current definition, none of the constraints defined for a "Cat" or "Dog" would be validated — only the ones defined for the "Pet".

Is this assumption correct? If yes, then I would assume that "oneOf" could be used here to restrict the values to "Cat" or "Dog" as intended.

Best regards
Martin

[handrews]

@mhonert we've added the following in the soon-to-be-published 3.1.1 and 3.0.4 versions, which should answer your question (see the part about what is and is not validated in the allOf pattern):

4.8.26.2 Conditions for Using the Discriminator Object

The Discriminator Object is legal only when using one of the composite keywords oneOf, anyOf, allOf.

In both the oneOf and anyOf use cases, where those keywords are adjacent to discriminator, all possible schemas MUST be listed explicitly.

To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas building on the parent schema via an allOf construct may be used as an alternate schema.

The allOf form of discriminator is only useful for non-validation use cases; validation with the parent schema with this form of discriminator does not perform a search for child schemas or use them in validation in any way. This is because discriminator cannot change the validation outcome, and no standard JSON Schema keyword connects the parent schema to the child schemas.

The behavior of any configuration of oneOf, anyOf, allOf and discriminator that is not described above is undefined.

[mhonert]

To better understand the background and possible motivations for the allOf/discriminator use case, I reviewed the different versions of the OpenAPI specification (including the former Swagger specifications).

Swagger 1.2 explicitly mentions the concept of "Inheritance" and provides the keywords "subTypes" and "discriminator" to express inheritance relationships between different schema models. These two attributes would be defined on the parent model, with "subTypes" explicitly listing all sub-models that inherit all properties from the parent model.

Swagger/OAS 2 retained the "discriminator" but removed the "subTypes" attribute. Instead, it introduced the "allOf" keyword from JSON Schema. Without the definition of a "discriminator," it essentially had the same "composition" semantics as in JSON Schema. However, when used in combination with a "discriminator," the semantics of "allOf" changed to also express an inheritance relationship between the sub-model containing the "allOf" and the referenced parent model. This seems to be the origin of the following statement from the specification, which still exists in OAS 3.0.x and 3.1.x:

While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, Swagger adds the support of the discriminator field.

I also found a discussion with a comment from someone named "Ron", who seemed to have worked on the Swagger/OAS 2 specification and/or documentation:

Unlike 1.2, there's no "subTypes". Any model that includes the super mode in the "allOf" definition will be considered a sub type of it.
So the super model is unaware of its children, but now the child is aware of its parent.

Then with OAS 3, the keywords "oneOf" and "anyOf" were added, providing additional ways to model polymorphic models.
What I do not know is whether the intention with OAS 3 was to either:

1. Keep the semantics of the allOf/discriminator use case from previous versions of the specification (perhaps to allow for a straightforward migration path from Swagger/OAS 2 to OAS 3)
2. Or to remove support for this way of modeling inheritance in favor of better JSON Schema compatibility.

I found statements supporting both possibilities in the specification (some of them were quoted in my previous response).

Before I can attempt a PR to clarify the related parts of the specifications, I need to know which direction it should take. From my limited overview of available tools for OAS 3, it seems that some still support the allOf/discriminator method to model inheritance from Swagger/OAS 2 (perhaps only accidentally due to how the modeling constructs are mapped to programming language-specific constructs?), while others only support a JSON Schema-compatible interpretation of "allOf".

[handrews]

@mhonert I have added this to this week's TDC call agenda. This is an open call, so if the time zone works out for you, please feel free to join us!

[mhonert]

@handrews Thank you! I won't be able to join, but I am looking forward to the outcome of the discussion.

[baywet]

We briefly discussed this on the call, and had a side chat as well, I figured I'd try to recap some of the thoughts that were shared here.

Assuming from a modeling perspective Cat and Dog derive from Pet.
Assuming you have an endpoint GET /listPets that describes returning Pets, but never actually returns a Pet, rather a mixed collection of Dogs and Cats.
With the current OAS capabilities, there are a couple of ways you can model this to the client code can easily deserialize the responses to the right type:

allOf +no discriminator

Pet:
   type: object
   properties
     name:
       type: string
Cat:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        purVolume:
          type: int
Dog:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        favoritePark:
          type: string

It's technically inaccurate since in this practical case, from a validation standpoint, nothing prevents you from returning a Pet even when it's not expected. Also the absence of discriminator requires the client to do some advanced pattern matching which is both complex to implement and costly at runtime.

allOf + discriminator

Pet:
   type: object
   properties
     name:
       type: string
     petKind:
       type: string
   discriminator:
      propertyName: petKind
      mappings:
      - Dog: '#Dog'
      - Cat: '#Cat'
Cat:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        purVolume:
          type: int
Dog:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        favoritePark:
          type: string

This is the most common approach, comes from OOP, static types, single inheritance, no support for union types languages that a lot of API are implemented with and developers are familiar with. It's technically inaccurate since in this practical case, from a validation standpoint, nothing prevents you from returning a Pet even when it's not expected.

oneOf - no discriminator

Pet:
   type: object
   properties
     name:
       type: string
   oneOf:
      - $ref: '#Dog'
      - $ref: '#Cat'
Cat:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        purVolume:
          type: int
Dog:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        favoritePark:
          type: string

This is hard on both OAS description generation tools and consumers, because they might run into a cyclic reference, or ignore some of the information.
Also the absence of discriminator requires the client to do some advanced pattern matching which is both complex to implement and costly at runtime.

oneOf - discriminator

Pet:
   type: object
   properties
     name:
       type: string
     petKind:
       type: string
   oneOf:
      - $ref: '#Dog'
      - $ref: '#Cat'
   discriminator:
      propertyName: petKind
      mappings:
      - Dog: '#Dog'
      - Cat: '#Cat'
Cat:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        purVolume:
          type: int
Dog:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        favoritePark:
          type: string

Solves the deserialization complexity, but the cyclic reference remains.

allOf + additional type for the response

Pet:
   type: object
   properties
     name:
       type: string
     petKind:
       type: string
Cat:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        purVolume:
          type: int
Dog:
   type: object
   allOf:
   - $ref: Pet
   - type: object
      properties:
        favoritePark:
          type: string
PetResponse: # the endpoints returns a collection of PetResponse instead of Pet in this example.
   type: object
   oneOf:
      - $ref: '#Dog'
      - $ref: '#Cat'
   discriminator:
      propertyName: petKind
      mappings:
      - Dog: '#Dog'
      - Cat: '#Cat'

Most accurate, avoids cyclic references, but some code generators might ignore some of the information here from experience due to the complexity of the modeling.

[baywet]

The crux of the issue here is that JSON Schema is a validation language, not an IDL. And OAS in its current form does not offer additional "hints" to model inheritance, etc... So we're effectively patching around it. And I believe we also have to account for what's in the wild today to avoid alienating the community.
As we revamp things, maybe having a sentence to add some context around inheritance modeling and its relation with discriminators would help if we don't already have it.

I think the general guidance should be along the lines of "allOf is NOT on its own a way to model inheritance", however it can be special cased as a proxy for it. Here are the general rules of thumb we have in kiota for the models projection:

• anyOf: inclusive union
• oneOf: exclusive union
• allOf (2 schemas, one inline, one $ref): inheritance.
• allOf (other cases): composed types which we mush into a single type for simplicity

For anyOf/oneOf/allOf we'll only support deserializing to a member object type if discriminator information is present (or downcasting to a child type in the case of allOf)

I hope all of (pun intended) this additional information helps :)

[miqui]

@ralfhandl and @mikekistler review

[mikekistler]

Let me add one more option to @baywet 's list:

oneOf - discriminator (not cyclic, "pure" JSON Schema with hint)

Pet:
  type: object
  properties
    petKind:
      type: string
  required: ['petKind']
  oneOf:
  - $ref: '#Dog'
  - $ref: '#Cat'
  discriminator:
    propertyName: petKind
    mappings:
      dog: '#Dog'
      cat: '#Cat'
PetBase:
  type: object
  properties
    name:
      type: string
Cat:
  allOf:
  - $ref: PetBase
  - properties:
      petKind:
        type: string
        enum: ['cat']
      purVolume:
         type: int
Dog:
  allOf:
  - $ref: PetBase
  - type: object
    properties:
      petKind:
        type: string
        enum: ['dog']
      favoritePark:
        type: string

This is the style that I prefer because:

• No cyclic refs
• The enum value is clearly defined in each variant of Pet
• This makes discriminator just a restatement of what is already clear from the schemas.

Defining the enum value in each variant is important because it eliminates the possibly of the oneOf failing to validate because the object matches more than one variant. It also makes the discriminator just a restatement of the information already present in the "pure" JSON schema.

[handrews]

I'm going to go ahead and close this because we have done our best to improve the wording around this in 3.0.4 and 3.1.1, which we believe will be out by October (we're just debating some final wording tweaks right now). Do feel free to open a new discussion if needed.