Rename ESQL version, add constants for default versions (#2534) (#2535)

Author: swallez

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!
 

output/schema/schema.json

@@ -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'

output/typescript/types.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
   }
 }