Implement union type validation for static language support

specification/_global/delete/DeleteResponse.ts

@@ -29,6 +29,7 @@ export class Response {
        * the response is the same as the successful case, but with a 404.
        */
       statusCodes: [404]
+      // eslint-disable-next-line es-spec-validator/no-inline-unions, es-spec-validator/prefer-tagged-variants -- TODO: use tagged variant
       body: WriteResponseBase | ErrorResponseBase
     }
   ]

specification/_global/get/GetResponse.ts

@@ -29,6 +29,7 @@ export class Response<TDocument> {
       //  * index_not_found_exception as an error if the index doesn't exist
       //  * GetResult with only the requested _id, _index properties and found as a false boolean
       statusCodes: [404]
+      // eslint-disable-next-line es-spec-validator/no-inline-unions, es-spec-validator/prefer-tagged-variants -- TODO: use tagged variant
       body: GetResult<TDocument> | ErrorResponseBase
     }
   ]

specification/_global/scripts_painless_execute/types.ts

@@ -97,5 +97,6 @@ export class PainlessScript {
    * * `long`: `emit(long)`
    * * `keyword`: `emit(String)`
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   emit: boolean | DateTime | double | string | Ip | long
 }

specification/_global/search/_types/hits.ts

@@ -52,6 +52,7 @@ export class Hit<TDocument> {
   fields?: Dictionary<string, UserDefinedValue>
   highlight?: Dictionary<string, string[]>
   inner_hits?: Dictionary<string, InnerHitsResult>
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   matched_queries?: string[] | Dictionary<string, double>
   _nested?: NestedIdentity
   _ignored?: string[]
@@ -69,6 +70,7 @@ export class Hit<TDocument> {
 
 export class HitsMetadata<T> {
   /** Total hit count information, present only if `track_total_hits` wasn't `false` in the search request. */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   total?: TotalHits | long
   hits: Hit<T>[]
 

specification/_global/search/_types/suggester.ts

@@ -186,6 +186,7 @@ export class RegexOptions {
    * Optional operators for the regular expression.
    * @doc_id regexp-syntax
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   flags?: integer | string
   /**
    * Maximum number of automaton states required for the query.

specification/_types/mapping/specialized.ts

@@ -44,6 +44,7 @@ export class SuggestContext {
   name: Name
   path?: Field
   type: string
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   precision?: integer | string
 }
 

specification/_types/query_dsl/compound.ts

@@ -143,6 +143,7 @@ export class ScriptScoreFunction {
 
 export class RandomScoreFunction {
   field?: Field
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   seed?: long | string
 }
 

specification/_types/query_dsl/fulltext.ts

@@ -395,6 +395,7 @@ export class MatchQuery extends QueryBase {
    */
   // FIXME: docs states "date" as a possible format. Add DateMath, or DurationLarge?
   //        Should also be consistent with MultiMatchQuery.query
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   query: string | float | boolean
   /**
    * Indicates whether no documents are returned if the `analyzer` removes all tokens, such as when using a `stop` filter.

specification/_types/query_dsl/term.ts

@@ -82,6 +82,7 @@ export class FuzzyQuery extends QueryBase {
   // ES is lenient and accepts any primitive type, but ultimately converts it to a string.
   // Changing this field definition from UserDefinedValue to string breaks a recording produced from Nest tests,
   // but Nest is probably also overly flexible here and exposes an option that should not exist.
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   value: string | double | boolean
 }
 

specification/eslint.config.js

@@ -35,6 +35,8 @@ export default defineConfig({
     'es-spec-validator/dictionary-key-is-string': 'error',
     'es-spec-validator/no-native-types': 'error',
     'es-spec-validator/invalid-node-types': 'error',
-    'es-spec-validator/no-generic-number': 'error'
+    'es-spec-validator/no-generic-number': 'error',
+    'es-spec-validator/no-inline-unions': 'error',
+    'es-spec-validator/prefer-tagged-variants': 'error'
   }
 })

specification/fleet/global_checkpoints/GlobalCheckpointsRequest.ts

@@ -43,6 +43,7 @@ export interface Request extends RequestBase {
     /**
      * A single index or index alias that resolves to a single index.
      */
+    // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
     index: IndexName | IndexAlias
   }
   query_parameters: {

specification/fleet/msearch/MultiSearchRequest.ts

@@ -54,6 +54,7 @@ export interface Request extends RequestBase {
     /**
      * A single target to search. If the target is an index alias, it must resolve to a single index.
      */
+    // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
     index?: IndexName | IndexAlias
   }
   query_parameters: {

specification/fleet/search/SearchRequest.ts

@@ -72,6 +72,7 @@ export interface Request extends RequestBase {
     /**
      * A single target to search. If the target is an index alias, it must resolve to a single index.
      */
+    // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
     index: IndexName | IndexAlias
   }
   query_parameters: {

specification/indices/_types/IndexRouting.ts

@@ -60,5 +60,6 @@ export class IndexRoutingAllocationInitialRecovery {
 
 // ES: DiskThresholdSettings
 export class IndexRoutingAllocationDisk {
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   threshold_enabled?: boolean | string
 }

specification/indices/_types/IndexSettings.ts

@@ -84,11 +84,13 @@ export class IndexSettings
    * @server_default 1
    * @availability stack
    * */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   number_of_shards?: integer | string // TODO: should be only int
   /**
    * @server_default 0
    * @availability stack
    * */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   number_of_replicas?: integer | string // TODO: should be only int
   number_of_routing_shards?: integer
   /** @server_default false */
@@ -100,6 +102,7 @@ export class IndexSettings
   /** @server_default true */
   load_fixed_bitset_filters_eagerly?: boolean
   /** @server_default false */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   hidden?: boolean | string // TODO should be bool only
   /** @server_default false */
   auto_expand_replicas?: WithNullValue<string>
@@ -147,11 +150,14 @@ export class IndexSettings
   creation_date_string?: DateTime
   uuid?: Uuid
   version?: IndexVersioning
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   verified_before_close?: boolean | string
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   format?: string | integer
   max_slices_per_scroll?: integer
   translog?: Translog
   query_string?: SettingsQueryString
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   priority?: integer | string
   top_metrics_max_size?: integer
   analysis?: IndexSettingsAnalysis
@@ -332,6 +338,7 @@ export class IndexSettingsLifecycle {
    * applicable for an index).
    * @server_default true
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   prefer_ilm?: boolean | string
 }
 
@@ -448,6 +455,7 @@ export class MappingLimitSettings {
   field_name_length?: MappingLimitSettingsFieldNameLength
   dimension_fields?: MappingLimitSettingsDimensionFields
   source?: MappingLimitSettingsSourceFields
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   ignore_malformed?: boolean | string
 }
 
@@ -458,6 +466,7 @@ export class MappingLimitSettingsTotalFields {
    * degradations and memory issues, especially in clusters with a high load or few resources.
    * @server_default 1000
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   limit?: long | string
   /**
    * This setting determines what happens when a dynamically mapped field would exceed the total fields limit. When set
@@ -467,6 +476,7 @@ export class MappingLimitSettingsTotalFields {
    * The fields that were not added to the mapping will be added to the _ignored field.
    * @server_default false
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   ignore_dynamic_beyond_limit?: boolean | string
 }
 

specification/indices/get_alias/IndicesGetAliasResponse.ts

@@ -31,6 +31,7 @@ export class Response {
   exceptions: [
     {
       statusCodes: [404]
+      // eslint-disable-next-line es-spec-validator/no-inline-unions, es-spec-validator/prefer-tagged-variants -- TODO: use tagged variant
       body: NotFoundAliases | ErrorResponseBase
     }
   ]

specification/inference/completion/CompletionRequest.ts

@@ -60,7 +60,7 @@ export interface Request extends RequestBase {
      * Inference input.
      * Either a string or an array of strings.
      */
-    input: string | Array<string>
+    input: string | string[]
     /**
      * Task settings for the individual inference request. These settings are specific to the <task_type> you specified and override the task settings specified when initializing the service.
      */

specification/inference/inference/InferenceRequest.ts

@@ -81,7 +81,7 @@ export interface Request extends RequestBase {
      * > info
      * > Inference endpoints for the `completion` task type currently only support a single string as input.
      */
-    input: string | Array<string>
+    input: string | string[]
     /**
      * Specifies the input data type for the text embedding model. The `input_type` parameter only applies to Inference Endpoints with the `text_embedding` task type. Possible values include:
      * * `SEARCH`

specification/inference/sparse_embedding/SparseEmbeddingRequest.ts

@@ -54,7 +54,7 @@ export interface Request extends RequestBase {
      * Inference input.
      * Either a string or an array of strings.
      */
-    input: string | Array<string>
+    input: string | string[]
     /**
      * Task settings for the individual inference request. These settings are specific to the <task_type> you specified and override the task settings specified when initializing the service.
      */

specification/inference/text_embedding/TextEmbeddingRequest.ts

@@ -54,7 +54,7 @@ export interface Request extends RequestBase {
      * Inference input.
      * Either a string or an array of strings.
      */
-    input: string | Array<string>
+    input: string | string[]
     /**
      * The input data type for the text embedding model. Possible values include:
      * * `SEARCH`

specification/nodes/info/types.ts

@@ -143,6 +143,7 @@ export class NodeInfoSettingsCluster {
   name: Name
   routing?: IndexRouting
   election: NodeInfoSettingsClusterElection
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   initial_master_nodes?: string[] | string
   /**
    * @availability stack since=7.16.0
@@ -152,6 +153,7 @@ export class NodeInfoSettingsCluster {
 }
 
 export class DeprecationIndexing {
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   enabled: boolean | string
 }
 
@@ -186,6 +188,7 @@ export class NodeInfoRepositoriesUrl {
 export class NodeInfoDiscover
   implements AdditionalProperties<string, UserDefinedValue>
 {
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   seed_hosts?: string[] | string
   type?: string
   seed_providers?: string[]
@@ -202,7 +205,9 @@ export class NodeInfoClient {
 export class NodeInfoSettingsHttp {
   type: NodeInfoSettingsHttpType
   'type.default'?: string // TODO this clashes with NodeInfoSettingsHttpType
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   compression?: boolean | string
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   port?: integer | string
 }
 
@@ -376,6 +381,7 @@ export class NodeJvmInfo {
   vm_vendor: string
   vm_version: VersionString
   using_bundled_jdk: boolean
+  // eslint-disable-next-line es-spec-validator/no-inline-unions -- TODO: create named alias
   using_compressed_ordinary_object_pointers?: boolean | string
   input_arguments: string[]
 }

specification/security/_types/RoleDescriptor.ts

@@ -55,6 +55,7 @@ export class RoleDescriptor {
    * An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
    * @availability stack
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions, es-spec-validator/prefer-tagged-variants -- TODO: use tagged variant
   global?: GlobalPrivilege[] | GlobalPrivilege
   /**
    * A list of application privilege entries
@@ -106,6 +107,7 @@ export class RoleDescriptorRead implements OverloadOf<RoleDescriptor> {
   /**
    * An object defining global privileges. A global privilege is a form of cluster privilege that is request-aware. Support for global privileges is currently limited to the management of application privileges.
    */
+  // eslint-disable-next-line es-spec-validator/no-inline-unions, es-spec-validator/prefer-tagged-variants -- TODO: use tagged variant
   global?: GlobalPrivilege[] | GlobalPrivilege
   /**
    * A list of application privilege entries

validator/README.md

@@ -12,6 +12,8 @@ It is configured [in the specification directory](../specification/eslint.config
 | `no-native-types`                     | `Typescript native types not allowed, use aliases. |
 | `invalid-node-types`                  | The spec uses a subset of TypeScript, so some types, clauses and expressions are not allowed. |
 | `no-generic-number`                   | Generic `number` type is not allowed outside of `_types/Numeric.ts`. Use concrete numeric types like `integer`, `long`, `float`, `double`, etc. |
+| `no-inline-unions`                    | Inline union types (e.g., `field: A \| B`) are not allowed in properties/fields. Define a named type alias instead to improve code generation for statically-typed languages. |
+| `prefer-tagged-variants`              | Union of class types should use tagged variants (`@variants internal` or `@variants container`) instead of inline unions for better deserialization support in statically-typed languages. |
 
 ## Usage
 

validator/eslint-plugin-es-spec.js

@@ -21,6 +21,8 @@ import dict from './rules/dictionary-key-is-string.js'
 import noNativeTypes from './rules/no-native-types.js'
 import invalidNodeTypes from './rules/invalid-node-types.js'
 import noGenericNumber from './rules/no-generic-number.js'
+import noInlineUnions from './rules/no-inline-unions.js'
+import preferTaggedVariants from './rules/prefer-tagged-variants.js'
 
 export default {
   rules: {
@@ -29,5 +31,7 @@ export default {
     'no-native-types': noNativeTypes,
     'invalid-node-types': invalidNodeTypes,
     'no-generic-number': noGenericNumber,
+    'no-inline-unions': noInlineUnions,
+    'prefer-tagged-variants': preferTaggedVariants,
   }
 }