From 3fbd0d90ad67872f893cacc22a39a5bf3cee7a39 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Laurent=20Saint-F=C3=A9lix?= <laurent.saintfelix@elastic.co>
Date: Thu, 19 Jun 2025 15:27:43 +0200
Subject: [PATCH] [compiler] Rename external to typed_keys_quirk (#4619)

* rename external to typed_keys_quirk in compiler

* propagate renaming to the specification files

* adapt the documentation to reflect the new name

* enhance typed_keys_quirk warning usage for contributors

Co-authored-by: Sylvain Wallez <sylvain@elastic.co>

---------

Co-authored-by: Sylvain Wallez <sylvain@elastic.co>
(cherry picked from commit d2baac05f69e788ab1e4cd8e46bce40c2722cf1b)
---
 compiler/src/model/utils.ts                      |  2 +-
 docs/modeling-guide.md                           | 12 +++++++-----
 specification/_global/search/_types/suggester.ts |  2 +-
 specification/_types/aggregations/Aggregate.ts   |  2 +-
 specification/ml/_types/inference.ts             |  2 +-
 specification/security/query_api_keys/types.ts   |  2 +-
 6 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/compiler/src/model/utils.ts b/compiler/src/model/utils.ts
index fd5c24107a..a845e1e3e7 100644
--- a/compiler/src/model/utils.ts
+++ b/compiler/src/model/utils.ts
@@ -1094,7 +1094,7 @@ export function parseVariantsTag (jsDoc: JSDoc[]): model.Variants | undefined {
   const nonExhaustive = (typeof tags.non_exhaustive === 'string') ? true : undefined
 
   const [type, ...values] = tags.variants.split(' ')
-  if (type === 'external') {
+  if (type === 'typed_keys_quirk') {
     return {
       kind: 'external_tag',
       nonExhaustive: nonExhaustive
diff --git a/docs/modeling-guide.md b/docs/modeling-guide.md
index 5ec0f5a8c1..974bb4589e 100644
--- a/docs/modeling-guide.md
+++ b/docs/modeling-guide.md
@@ -332,7 +332,9 @@ type FooOrBar = Foo | Bar
 
 An example of internal variants are the type mapping properties.
 
-#### External
+#### typed_keys_quirk
+
+**Note**: this feature exists because of some early Elasticsearch APIs where tagging was forgotten, and added after the fact using this quirk to avoid breaking compatibility. **It should not be used for new APIs.**
 
 The key that defines the variant is external to the definition, like in the
 case of aggregations in responses or suggesters.
@@ -343,7 +345,7 @@ name in the definition itself.
 The syntax is:
 
 ```ts
-/** @variants external */
+/** @variants typed_keys_quirk */
 
 /** @variant name='<field-name>' */
 ```
@@ -351,7 +353,7 @@ The syntax is:
 For example:
 
 ```ts
-/** @variants external */
+/** @variants typed_keys_quirk */
 type FooAlias = Faz | Bar
 
 /** @variant name='faz' */
@@ -369,7 +371,7 @@ In the example above, `FooAlias` will look like this:
 
 ```json
 {
-  "faz": {
+  "name#faz": {
     "prop": "hello world"
   }
 }
@@ -379,7 +381,7 @@ or:
 
 ```json
 {
-  "bar": {
+  "name#bar": {
     "prop": true
   }
 }
diff --git a/specification/_global/search/_types/suggester.ts b/specification/_global/search/_types/suggester.ts
index ba4727f503..a67482046f 100644
--- a/specification/_global/search/_types/suggester.ts
+++ b/specification/_global/search/_types/suggester.ts
@@ -32,7 +32,7 @@ import { Dictionary } from '@spec_utils/Dictionary'
 import { UserDefinedValue } from '@spec_utils/UserDefinedValue'
 
 /**
- * @variants external
+ * @variants typed_keys_quirk
  */
 export type Suggest<TDocument> =
   | CompletionSuggest<TDocument>
diff --git a/specification/_types/aggregations/Aggregate.ts b/specification/_types/aggregations/Aggregate.ts
index 05fb9d3a1e..ed1e685bb6 100644
--- a/specification/_types/aggregations/Aggregate.ts
+++ b/specification/_types/aggregations/Aggregate.ts
@@ -36,7 +36,7 @@ import { UserDefinedValue } from '@spec_utils/UserDefinedValue'
 import { Void } from '@spec_utils/VoidValue'
 
 /**
- * @variants external
+ * @variants typed_keys_quirk
  * @non_exhaustive
  * @ext_doc_id search-aggregations
  */
diff --git a/specification/ml/_types/inference.ts b/specification/ml/_types/inference.ts
index 11ee015d60..75aafa1f20 100644
--- a/specification/ml/_types/inference.ts
+++ b/specification/ml/_types/inference.ts
@@ -91,7 +91,7 @@ export class LearningToRankConfig {
 }
 
 /**
- * @variants external
+ * @variants typed_keys_quirk
  */
 export type FeatureExtractor = QueryFeatureExtractor
 
diff --git a/specification/security/query_api_keys/types.ts b/specification/security/query_api_keys/types.ts
index 77751e6772..946a6df924 100644
--- a/specification/security/query_api_keys/types.ts
+++ b/specification/security/query_api_keys/types.ts
@@ -120,7 +120,7 @@ export class ApiKeyAggregationContainer {
 }
 
 /**
- * @variants external
+ * @variants typed_keys_quirk
  * @non_exhaustive
  */
 export type ApiKeyAggregate =