Use of oneOf with a discriminator, when the child schemas are identical?

[davidjlynn]

Hello,
I have been trying to clean up a schema which is using oneOf, and have run into some issues which may be due to some bad understandings of how oneOf should be used, and hoped to get some guidance.

Situation

For an example I will use the Cat/Dog/Lizard/etc example, and for your information, I am using v3.0.1 of the spec (however this question seems relevant for at least all 3.x.y versions).

I have currently tried to use oneOf with a discriminator so that I can return a typed schema, and describe nicely what the child schemas will look like.

Note that in my example I have:

• Used a simple oneOf
• The pet_type field is present on all oneOf entities.
• I have added a new animal Snake which happens to have the same properties (currently, although may not in future) as Lizard.

This looks like so:

components:
  schemas:
    PetType:
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
        - $ref: '#/components/schemas/Lizard'
        - $ref: '#/components/schemas/Snake'
      discriminator:
        propertyName: pet_type
        mapping:
          CAT: '#/components/schemas/Cat'
          DOG: '#/components/schemas/Dog'
          LIZARD: '#/components/schemas/Lizard'
          SNAKE: '#/components/schemas/Snake'
    Cat:
      description: A representation of a cat
      type: object
      properties:
        pet_type:
          type: string
          description: The type of the Pet.
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
          - clueless
          - lazy
          - adventurous
          - aggressive
      required:
      - pet_type
      - huntingSkill
    Dog:
      description: A representation of a dog
      type: object
      properties:
        pet_type:
          type: string
          description: The type of the Pet.
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
      - pet_type
      - packSize
    Lizard:
      description: A representation of a lizard
      type: object
      properties:
        pet_type:
          type: string
          description: The type of the Pet.
        lovesRocks:
          type: boolean
      required:
      - pet_type
    Snake:
      description: A representation of a snake
      type: object
      properties:
        pet_type:
          type: string
          description: The type of the Pet.
        lovesRocks:
          type: boolean
      required:
      - pet_type

I had initially thought this was valid, but after some issues with code generation I wondered if it is not.

Looking at the Specification on Discriminator Objects it says:

the payload MUST, by validation, match exactly one of the schemas described by Cat, Dog, or Lizard. In this case, a discriminator MAY act as a "hint" to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema.

If I read this correctly, the "MUST" part says that the specification must be able to identify which schema a payload will map to using the field names and the presence of values alone, and the discriminator is an optional shortcut, but should be unnecessary.

And so, this above setup may not be valid, because there is no unique fields between Snake/Lizard to identify which type it is, without inspecting the field value of pet_type.

Concrete Observations

I was using some tooling for generation of these examples, so while I understand that the tooling is external to the specification, I will just give some details of what I observed. Feel free to ignore.

Using Swagger Editor showed no issues with the specification.

And while using OpenAPI Generator the specification again showed no warnings, and I saw:

• For Java Generation
  • Successful generation by default, using the discriminator field to switch between types which are the same.
• For C# Generation
  • Unsuccessful generation by default, but this might be overcome by using the option useOneOfDiscriminatorLookup (default false).

But, obviously these can be ignored as implementation specifics.

Question

Is it valid to have multiple schemas under a OneOf which fields are the same? And if not is there another recommended way to do this?
I would like to model this the "right" way, and clear up any misunderstandings I may have.
Even if I can get all the generation working with extra options, it would be good to ensure we follow the schema correctly.

My thoughts currently

I was especially considering how OneOf can handle schema evolution.
The above example only returns the needed information currently (under a reliable type with a discriminator that a consumer can rely on; SNAKE/LIZARD). And by having the ability to have these schemas the same for the moment, I can later decide to add new fields (like hasRattle to Snake) and these types can begin to deviate, in a non-breaking way (because I wouldn't need to change the value of pet_type).
While if the schemas need to be unique based on Field Presence alone, then it could be hard to avoid breaking changes while using OneOf.

If this is a valid pattern according to OAS, that is good, and I can continue to use the generator with the understanding that it should be supported.

If it is invalid, it feels like this will rule out the use of oneOf. And that the next best thing would be combining all these types simply into PetType with many optional fields. It would be less descriptive, but would in the end return the same information.

Thanks for any thoughts/advice.

[smikulcik]

Hey @davidjlynn , oneOfs are incredibly hard to understand. It's more about the a validation rule for a json instance than it is about a polymorphic "type system".

I wrote a blog to help folks sort this out https://medium.com/@smikulcik/oneof-explained-c0264c429735

But yeah. If you have two identical oneOf options. No JSON instance that validates against either of those options can validate against the oneOf object.

[handrews]

To elaborate on this: discriminator is about choosing a model based on a specific field value, and oneOf and anyOf are two different validation rules for having multiple models. If some of your models look the same, then you want anyOf. You only want oneOf if they are all mutually exclusive. The discriminator feature itself doesn't care which you use.

Since there haven't been any further questions or responses, I'm going to mark this thread as the reply and close the discussion. Please comment if you think it is unresolved and we can re-open it.

[zorba128]

Please take a look at similar discussion on softwaremill/tapir#3909

Long story short - to me it seems oneOf is natural choice for this kind of model, it is just usually used in a wrong way. If child schemas are identical - one needs hint. So

1. lets add pet_type to each of child schemas, and constraint it to single constant value: CAT (in the cat schema), DOG, ...

All done - it works perfectly. But we can do better I believe:
2. if all child schemas have this field - we can additionally define it on the parent level. so parent schema tells always there will be a field pet_type, and child schemas constraint it to specific value
3. we could mark this definition on generic level with some custom property to signal its discriminator role

All done - everything is precise, uses already existing concepts, parsers if they wish can build lookup tables for discriminator values, no need to store mapping table explicitly anywhere in the schema.