3.1.1: polymorphism and discriminator in request type

[hfhbd]

This line mentions the option to not repeat the child schemas using anyOf but the option to use a base type, here Pet:

OpenAPI-Specification/versions/3.1.1.md

Line 3379 in 428007d

This example shows the `allOf` usage, which avoids needing to reference all child schemas in the parent:

This example shows the allOf usage, which avoids needing to reference all child schemas in the parent

But how does a response type look like?

myResponseType:
  $ref: '#/components/schemas/Pet'

Is this all? How does the caller know a specific sub type of Pet like Cat is required and { "petType": "Cat" } is not allowed?

[handrews]

@hfhbd The allOf syntax for discriminator is weird for the reason you mention. Among others. We keep trying to explain it better, but AFAIK none of the people who came up with it are still active with the project, so it's a bit of archaeology and we keep finding new surprises.

What's going on here is that for validation purposes, the allOf approach only works if you are validating using a child schema, which means you already have to know what child it will be. This is because discriminator is not allowed to change the validation outcome, because doing so in the allOf case would outright contradict the JSON Schema specification, for reasons that are too complex to go into here. JSON Schema has proposed an alternate keyword that may get incorporated one day, but that's more a question for them than for us.

@mikekistler is working on the latest attempt to improve discriminator, which you can read at #4339. We'll keep trying to improve the explanation in future releases. Ultimately, it needs to be replaced with something more compatible with JSON Schema validation (or whatever gets used for data definition and validation in 4.0 "Moonwalk.")

I know that's not a satisfactory answer, but it's the best I have for you. discriminator was designed from a code generation perspective, doing static analysis on the OpenAPI Description, independent of runtime value. JSON Schema, on the other hand, is a runtime constraint system, which is a completely different design approach. The approaches collide badly in the allOf form of discriminator.

[hfhbd]

Thanks for the answer! Well, as a library author of a code generator for Kotlin, a static typed language and its serialization compiler plugin, I am absolutely okay with current design from code generation view that requires a descriptor, but was just curious, how it should work from runtime view with a more relaxed/dynamic language/framework.

[handrews]

@hfhbd

but was just curious, how it should work from runtime view with a more relaxed/dynamic language/framework.

Yeah, and the unsatisfactory answer is "it kinda doesn't."