Additional Information for type_alias items.

[stevejgordon]

We have various type_alias definitions which represent a union of two possible instance items. Often these are fairly primitive types such as this example for MinimumShouldMatch.

{
  "kind": "type_alias",
  "name": {
	"name": "MinimumShouldMatch",
	"namespace": "common_options.minimum_should_match"
  },
  "type": {
	"items": [
	  {
		"kind": "instance_of",
		"type": {
		  "name": "integer",
		  "namespace": "internal"
		}
	  },
	  {
		"kind": "instance_of",
		"type": {
		  "name": "string",
		  "namespace": "internal"
		}
	  }
	],
	"kind": "union_of"
  },
  "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-minimum-should-match.html"
}

In the existing NEST client, we provide a type deriving from our Union<T1, T2> base. For MinimumShouldMatch it provides constructors to initialise it with either a string or integer. We also provide two factory methods in this example to make it clearer and easier to create an instance. For example, we allow a double value to be provided as an argument, which we then format as a percentage string.

public class MinimumShouldMatch : Union<int?, string>
public class MinimumShouldMatch : Union<int?, string>
{
    public MinimumShouldMatch(int count) : base(count) { }
    public MinimumShouldMatch(string percentage) : base(percentage) { }

    public static MinimumShouldMatch Fixed(int count) => count;
    public static MinimumShouldMatch Percentage(double percentage) => $"{percentage}%";
}

The current schema does not encode enough information to support generating these rich, user-friendly types and I wanted to open a discussion around this.

On the code generator sync on Monday, we did consider the option of using a type_alias representing Percentage and either Fixed or Count as appropriate. The Union would then use those type aliases, rather than the primitive types. This has some advantages in that we can create these richer types during code generation. However, it may see an explosion of the number of type aliases in the schema.

Even using type aliases, I'm not sure how/if we'd like to encode sufficient information into the model to support strongly-typed clients providing rich creation of a percentage string from a double.

[swallez]

Minimum should match is one of the incarnations of fields that are actually a DSL-a-string (and even in numbers) with things like "2<-25% 9<-3" which is actually a list of pairs.

There's not much we can capture in the type definition beyond string | number. The spec can however provide a "signal" that this type probably deserves a special treatment to provide a good user experience in clients. Adding this signalling is a decision taken by the spec writer using their best judgement.

Code generators can then look for this signal to identify those types requiring special attention, maintaining a list of those that were already handled (either in a special way or just left as is). They should then fail if a new special type appears in the input spec that is not present in their internal list, triggering attention of the client's developer.

This signaling could be as follows (naming is hard, just a proposal):

/**
 * @complex_semantics
 */
type MinimumShouldMatch = integer | string

[philkra]

Is this issue still relevant?