Improve declaration of untagged unions to allow for generator optimizations

[flobernd]

Problem

RangeQuery is currently declared as:

/** @codegen_names date, number, terms */
// Note: deserialization depends on value types
export type RangeQuery = DateRangeQuery | NumberRangeQuery | TermsRangeQuery

This declaration is highly problematic for statically typed clients as there is no way to correctly deserialize into the correct union variant, because for example the following variants share the same underlying JSON type:

export class TermsRangeQuery extends RangeQueryBase {
  gt?: string

export class DateRangeQuery extends RangeQueryBase {
  gt?: DateMath // string

There are more types for which the same issue applies, for example:

/** @codegen_names date, numeric, geo */
// Note: deserialization depends on value types
export type DecayFunction =
  | DateDecayFunction
  | NumericDecayFunction
  | GeoDecayFunction

/** @codegen_names geo, date */
// Note: deserialization depends on value types
export type DistanceFeatureQuery =
  | GeoDistanceFeatureQuery
  | DateDistanceFeatureQuery

Proposal

Rearrange and mark these kind of untagged unions, that only differ by the type of some fields, in a specific way so that code generators can drive specialized generation to allow for asymmetric (de-)serialization:

export class MyTypeBase<T1, T2, ...> { ... }

export class MyTypeSpecialized1 extends MyTypeBase<int> {}
export class MyTypeSpecialized2 extends MyTypeBase<string> {}
export class MyTypeSpecialized3 extends MyTypeBase<bool> {}

/**
 * @codegen_names 1, 2, 3 
 * @variant untagged
 */
// Note: deserialization depends on value types
export type MyType = MyTypeSpecialized1 | MyTypeSpecialized2 | MyTypeSpecialized3 

In .NET world, the resulting class design could look like this:

// Untyped/any variant always used for deserialization; can optionally be used by the user when building queries
public class RangeQuery
{
    public object? Gt { get; set; }
}

public abstract class GenericRangeQuery<T> : RangeQuery
{
    public new T? Gt { get; set; }
}

// Specialized range query for numbers
public sealed class NumberRangeQuery : GenericRangeQuery<double> { }

// Specialized range query for dates
public sealed class DateRangeQuery : GenericRangeQuery<DateMath> { }

---

Motivation and initial discussion: #2545

[swallez]

Can you add a brief description of this new variant type in the docs?

And mentioning explicitly that this is used for legacy types and should generally avoided as it results in less optimal code generation in client libraries.

[flobernd]

Done.

[l-trotta]

@swallez added a commit to fix openapi generation (also enhanced error logging for the deserialization of the schema.json, thanks @Anaethelion)

[flobernd]

Spec Meeting 2024/06/27

1. Explicitly name the "deserialization"/untyped variant in the decorator
2. Add a strong validation to disallow adding new "untagged" variants
3. Check flattening of generics

[Anaethelion]

LGTM!