[compiler] Rename external to typed_keys_quirk (#4619) (#4622)

* 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



---------


(cherry picked from commit d2baac0)

Co-authored-by: Laurent Saint-Félix <[email protected]>
Co-authored-by: Sylvain Wallez <[email protected]>

Author: 3 people

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

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,15 +345,15 @@ name in the definition itself.
 The syntax is:
 
 ```ts
-/** @variants external */
+/** @variants typed_keys_quirk */
 
 /** @variant name='<field-name>' */
 ```
 
 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
   }
 }

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>

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
  */

specification/ml/_types/inference.ts

@@ -91,7 +91,7 @@ export class LearningToRankConfig {
 }
 
 /**
- * @variants external
+ * @variants typed_keys_quirk
  */
 export type FeatureExtractor = QueryFeatureExtractor
 

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 =