From 5305606c85c45d29f6620622cb6b265a50b5b9a6 Mon Sep 17 00:00:00 2001
From: Sylvain Wallez <sylvain@elastic.co>
Date: Fri, 26 Apr 2024 16:09:15 +0200
Subject: [PATCH] Rename ESQL version, add constants for default versions

---
 compiler/src/steps/validate-model.ts          | 11 +++++--
 output/schema/schema.json                     | 32 +++++++++++++++++--
 output/typescript/types.ts                    |  8 +++--
 .../_types/{Version.ts => EsqlVersion.ts}     | 21 +++++++++++-
 specification/esql/query/QueryRequest.ts      |  4 +--
 5 files changed, 66 insertions(+), 10 deletions(-)
 rename specification/esql/_types/{Version.ts => EsqlVersion.ts} (52%)

diff --git a/compiler/src/steps/validate-model.ts b/compiler/src/steps/validate-model.ts
index b1c1440079..2a267332ae 100644
--- a/compiler/src/steps/validate-model.ts
+++ b/compiler/src/steps/validate-model.ts
@@ -21,6 +21,7 @@ import * as model from '../model/metamodel'
 import { ValidationErrors } from '../validation-errors'
 import { JsonSpec } from '../model/json-spec'
 import assert from 'assert'
+import {TypeName} from "../model/metamodel";
 
 // Superclasses (i.e. non-leaf types, who are inherited or implemented) that are ok to be used as field types because
 // they're used as definition reuse and not as polymorphic types.
@@ -170,8 +171,14 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
     })
   }
 
-  // ErrorResponse is not referenced anywhere, but any API could return it if an error happens.
-  validateTypeRef({ namespace: '_types', name: 'ErrorResponseBase' }, undefined, new Set())
+  const additionalRoots: TypeName[] = [
+    // ErrorResponse is not referenced anywhere, but any API could return it if an error happens.
+    { namespace: '_types', name: 'ErrorResponseBase' },
+    // ESQL base versions are pseudo-constants
+    { namespace: 'esql._types', name: 'BaseStatefulEsqlVersion' },
+    { namespace: 'esql._types', name: 'BaseServerlessEsqlVersion' }
+  ]
+  additionalRoots.forEach(t => validateTypeRef(t, undefined, new Set()))
 
   // -----  Alright, let's go!
 
diff --git a/output/schema/schema.json b/output/schema/schema.json
index a33fd64666..8dc13e63aa 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -112067,6 +112067,32 @@
       },
       "specLocation": "eql/search/types.ts#L20-L32"
     },
+    {
+      "description": "Version of the ES|QL language that should be used by default in serverless client libraries.\n\nThis value is guaranteed to be stable for a given value of the Serverless API version, even if newer versions\nof the ES|QL language are added within that API version.",
+      "kind": "type_alias",
+      "name": {
+        "name": "BaseServerlessEsqlVersion",
+        "namespace": "esql._types"
+      },
+      "specLocation": "esql/_types/EsqlVersion.ts#L43-L49",
+      "type": {
+        "kind": "literal_value",
+        "value": "2024.04.01"
+      }
+    },
+    {
+      "description": "Version of the ES|QL language that should be used by default in stateful client libraries.\n\nThis value is guaranteed to be stable within a major version of the Elastic Stack, even if newer versions\nof the ES|QL language are added within that major version.",
+      "kind": "type_alias",
+      "name": {
+        "name": "BaseStatefulEsqlVersion",
+        "namespace": "esql._types"
+      },
+      "specLocation": "esql/_types/EsqlVersion.ts#L35-L41",
+      "type": {
+        "kind": "literal_value",
+        "value": "2024.04.01"
+      }
+    },
     {
       "kind": "enum",
       "members": [
@@ -112077,10 +112103,10 @@
         }
       ],
       "name": {
-        "name": "Version",
+        "name": "EsqlVersion",
         "namespace": "esql._types"
       },
-      "specLocation": "esql/_types/Version.ts#L20-L29"
+      "specLocation": "esql/_types/EsqlVersion.ts#L20-L29"
     },
     {
       "attachedBehaviors": [
@@ -112160,7 +112186,7 @@
             "type": {
               "kind": "instance_of",
               "type": {
-                "name": "Version",
+                "name": "EsqlVersion",
                 "namespace": "esql._types"
               }
             }
diff --git a/output/typescript/types.ts b/output/typescript/types.ts
index b15508f039..2c1f78ace2 100644
--- a/output/typescript/types.ts
+++ b/output/typescript/types.ts
@@ -9778,7 +9778,11 @@ export type EqlSearchResponse<TEvent = unknown> = EqlEqlSearchResponseBase<TEven
 
 export type EqlSearchResultPosition = 'tail' | 'head'
 
-export type EsqlVersion = '2024.04.01'
+export type EsqlBaseServerlessEsqlVersion = '2024.04.01'
+
+export type EsqlBaseStatefulEsqlVersion = '2024.04.01'
+
+export type EsqlEsqlVersion = '2024.04.01'
 
 export interface EsqlQueryRequest extends RequestBase {
   format?: string
@@ -9789,7 +9793,7 @@ export interface EsqlQueryRequest extends RequestBase {
     locale?: string
     params?: ScalarValue[]
     query: string
-    version: EsqlVersion
+    version: EsqlEsqlVersion
   }
 }
 
diff --git a/specification/esql/_types/Version.ts b/specification/esql/_types/EsqlVersion.ts
similarity index 52%
rename from specification/esql/_types/Version.ts
rename to specification/esql/_types/EsqlVersion.ts
index 17002fe488..f8e3a9658f 100644
--- a/specification/esql/_types/Version.ts
+++ b/specification/esql/_types/EsqlVersion.ts
@@ -20,10 +20,29 @@
 /**
  * The version of the ES|QL language in which the "query" field was written.
  */
-export enum Version {
+export enum EsqlVersion {
   /**
    * Run against the first version of ES|QL.
    * @codegen_name V2024_04_01
    */
   '2024.04.01'
 }
+
+// Note: ideally this should be a constant of type EsqlVersion, but the schema.json model doesn't
+// has support for this. So define a new type that is just a literal value, to be used by code generators.
+
+/**
+ * Version of the ES|QL language that should be used by default in stateful client libraries.
+ *
+ * This value is guaranteed to be stable within a major version of the Elastic Stack, even if newer versions
+ * of the ES|QL language are added within that major version.
+ */
+export type BaseStatefulEsqlVersion = '2024.04.01'
+
+/**
+ * Version of the ES|QL language that should be used by default in serverless client libraries.
+ *
+ * This value is guaranteed to be stable for a given value of the Serverless API version, even if newer versions
+ * of the ES|QL language are added within that API version.
+ */
+export type BaseServerlessEsqlVersion = '2024.04.01'
diff --git a/specification/esql/query/QueryRequest.ts b/specification/esql/query/QueryRequest.ts
index 8bcb1c466b..535f7b5d29 100644
--- a/specification/esql/query/QueryRequest.ts
+++ b/specification/esql/query/QueryRequest.ts
@@ -20,7 +20,7 @@
 import { RequestBase } from '@_types/Base'
 import { QueryContainer } from '@_types/query_dsl/abstractions'
 import { ScalarValue } from '@_types/common'
-import { Version } from '@esql/_types/Version'
+import { EsqlVersion } from '@esql/_types/EsqlVersion'
 
 /**
  * Executes an ES|QL request
@@ -64,6 +64,6 @@ export interface Request extends RequestBase {
     /**
      * The version of the ES|QL language in which the "query" field was written.
      */
-    version: Version
+    version: EsqlVersion
   }
 }