Invalid OA3 for unions

[bterlson]

We are not emitting proper OA3 for unions. In this example, I believe we need to emit oneOf somewhere. Right now we depend on references to the base type implicitly being a reference to some kind of union of anything that allOf's that type, but these semantics are not supported by the specification. @mikekistler agrees with this analysis.

oneOf two things need to happen for out output to be correct:

1. Any references to Base are replaced by an inline oneOf union referencing all of the derived types.
2. Base becomes an allOf of the derived types and we generate a new type with a name like BaseCommon that holds the cadl Base type's properties.

The latter is what @mikekistler prefers, and hinges on the fact that by putting discriminator on the base model you're essentially instructing cadl that "every time I reference this type, I'm referring to a union of its subtypes", but it does have the downside that we are generating a name in the openapi output (BaseCommon), and also munging a name users might expect to be generated as-is in client code (e.g. they might expect to see class A extends Base { } in their TS/C# code somewhere.

We have a third option here which is to delete @Discriminator on models and reserve it only for unions ala #335 where the Cadl author gives a good name to both the base type and the union separately.

[timotheeguerin]

I don't think oneOf is required for openapi3, in the specs there is a sample that use allOf uniquely https://swagger.io/specification/#schema-composition

[mikekistler]

This is a complicated topic so let's avoid potential confusion of using non-authoritative sources like swagger.io. Let's just use the official OpenAPI v3.0 spec at:

https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md

The important part for this discussion is:

In both the oneOf and anyOf use cases, all possible schemas MUST be listed explicitly. To avoid redundancy, the discriminator MAY be added to a parent schema definition, and all schemas comprising the parent schema in an allOf construct may be used as an alternate schema.

Brian convinced me that what this really means is: Rather than repeating the property definition for the discriminator in every schema that will be named in an anyOf or oneOf, you can create a "parent schema" with the discriminator and allOf this into the "alternate schema" (of the anyOf or oneOf). So allOf does not replace an anyOf or oneOf, but rather it simply allows "avoiding redundancy" when constructing it.

@darrelmiller Could you give your thoughts on this?

[bterlson]

I saw the example @timotheeguerin posted and pondered for some time. The issue is it doesn't show usage of those types. I think to use dog and cat you would have to use a oneOf/anyOf at the usage site, or reference a schema that does so.

[timotheeguerin]

Talking a bit offline with @bterlson and looking at some of the openapi3 specs issues. In this one on particular OAI/OpenAPI-Specification#2165 (comment) there is some clarfication on the requirement of oneOf or anyOf

To be clear, the oneOf or enum constraint on Reptile isn't required for discriminator to work. If you're using an OpenAPI-compliant validator, it should extend validation to the specified schema as described above. The only purpose of the oneOf or enum in Reptile is to make sure that a request or response specified as Reptile will only pass validation if it is one of the known Reptile subtypes.

With this feels like we are doing the right thing for the extends scenario.

[markcowl]

estimate: 8

[markcowl]

remove from design board.