Behavior of the allOf and discriminator

[mtovt]

Hello! I have a few pieces of questions related to a combination of allOf and discriminator usage.

I have following OpenAPI spec

openapi: 3.0.3
info:
  title: 'Example'
  version: 0.1.0
servers:
  - url: 'http://example.com'
paths:
  ‘/users’:
    get:
      responses:
        '200':
          description: OK
          content: 
            application/json:
              schema:
                type: array
                items: 
                  $ref: "#/components/schemas/User"
components:
  schemas:
    User:
      type: object
      properties:
        $type:
          type: string
        shared_property:
          type: string
      discriminator:
        propertyName: "$type"

    UserA:
      allOf: [
        $ref: "#/components/schemas/User"
        ]
      type: object
      properties:
        foo:
          type: string


    UserB:
      allOf: [
        $ref: "#/components/schemas/User"
        ]
      type: object
      properties:
        bar:
          type: string

In case of GET request to /users server must return an array of Users and their subtypes (UserA, UserB).

1. Is that right or User do not includes their subtypes (UserA, UserB) in this context? Seems I should define response as oneOf: [User, UserA, UserB] for correctness?

I have doubts because I use this spec to generate python client using openapi-generator. And in generated User model I see following code

…

def discriminator():
    lazy_import()
    val = {
        'UserA': UserA,
        'UserB': UserB,
    }

…

Seems like User knows about UserA and UserB and tries to parse data into them if eg $type=UserA. But no User model himself here. So parsing fails when I get an object with $type=User. That seems strange.

It may be fixed in 2 ways

• oneOf: [User, UserA, UserB] in endpoint response.
• add discriminator/mapping field, where explicitly add User schema into discriminator mapping.

2. Is openapi generator implement this in the correct way?
3. What is the convenient way to specify that server returns an array, that may contain types: User, UserA, UserB?

[rafalkrupinski]

allOf makes it an inheritance. Superclass should neither know of nor include its subclasses.

The specification you've attached says your endpoint returns only a list of User. Since additionalProperties is true by default, it may return objects that happen to validate against UserA and/or UserB but that's not declared explicitly.

responses:
  default:
    content:
      application/json:
        schema:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/UserA'
            - $ref: '#/components/schemas/UserB'
            - $ref: '#/components/schemas/User'

Not sure about discriminator, but you can try adding additionalProperties: false to User schema, so that UserA&B don't validate against it.

[rafalkrupinski]

allOf makes it an inheritance. Superclass should neither know of nor include its subclasses.

It's not correct. Do not think about allOf like it's an inheritance. It's an intersection. It means a value should be valid against all schemas listed in allOf. And if some schemas in allOf are mutually exclusive (e.g. first schema has type: string and second type: number), a value will never be valid against such schema.

That's not how intersection works. I think you meant union, which in python terms (OP is clearly a python dev) is IMO best described as multiple inheritance, with single inheritance as a special case (python Union is more like OAS oneOf).

Best Regards

[flaksp]

Sorry, I meant intersection type defined by type theory 🙂

And when you combine two mutually exclusive schemas, they result into bottom type (which is basically Never or Nothing in some languages). Inheritance allows you to overwrite and access some properties of a parent structure. But there is no thing like overwriting properties of schemas in the JSON Schema specification. If you try to "overwrite" something using $ref or allOf, it may result into Never, which is undesired in most cases for schema authors.

Also, there is official warning by JSON Schema authors about using allOf for inheritance purposes:

allOf can not be used to “extend” a schema to add more details to it in the sense of object-oriented inheritance. Instances must independently be valid against “all of” the schemas in the allOf.

[rafalkrupinski]

Thank you @flaksp for pointing this out and for the links.

What I've wrote holds only in this example, which has no conflicting properties, which I did mention, and the base schema allows additional properties, which I didn't.

Using inheritance doesn't automatically stop your instances from validating against such schema. You just can't expect it will just work in every case.

In this particular example, if you map User schema to a class, UserA and UserB to subclasses each of which only adds a new field, and User schema doesn't have additionalProperties=true, instances of User, UserA and UserB all validate against User schema.

Even if you had UserC defined as allOf: [UserA, UserB], and on the python side: class UserC(UserA, UserB):pass, an instance of that class would still validate against User schema, because of no overlapping properties and no limit on additional properties.

Kind Regards

[rafalkrupinski]

[continuing my first answer]
@mtovt On the second thought, while generally superclasses don't need to know about their subclasses (although Python has the notion of registering subclasses), in case of using a discriminator you need to store the mapping of discriminator value to schema/class, and the top class is just the most obvious place. So it's an implementation detail.

Still, reading your schema, I never expect to receive instance of either UserA or UserB from this endpoint.
On the other hand, neither way is wrong. A JSON object that validates against UserA or UserB schemas, also validates against User. It's a matter of expressing your intentions.

Kind Regards

[mtovt]

@rafalkrupinski @flaksp Thanks so much for your discussion and explanations! It makes it more evident to me.

[handrews]

Answer accepted, closing.