Add the "es_quirk" annotation to capture snowflakes in ES behavior (#1674) (#1678)

Author: swallez

compiler/src/model/metamodel.ts

@@ -139,6 +139,8 @@ export class Property {
   aliases?: string[]
   /** If the enclosing class is a variants container, is this a property of the container and not a variant? */
   containerProperty?: boolean
+  /** If this property has a quirk that needs special attention, give a short explanation about it */
+  esQuirk?: string
 }
 
 // ------------------------------------------------------------------------------------------------
@@ -158,6 +160,8 @@ export abstract class BaseType {
   docUrl?: string
   docId?: string
   deprecation?: Deprecation
+  /** If this endpoint has a quirk that needs special attention, give a short explanation about it */
+  esQuirk?: string
   kind: string
   /** Variant name for externally tagged variants */
   variantName?: string

compiler/src/model/utils.ts

@@ -439,6 +439,10 @@ export function modelEnumDeclaration (declaration: EnumDeclaration): model.Enum
     type.isOpen = true
   }
 
+  if (typeof tags.es_quirk === 'string') {
+    type.esQuirk = tags.es_quirk
+  }
+
   return type
 }
 
@@ -639,7 +643,8 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
   // We want to enforce a single jsDoc block.
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
-  const validTags = ['class_serializer', 'doc_url', 'doc_id', 'behavior', 'variants', 'variant', 'shortcut_property', 'codegen_names', 'non_exhaustive']
+  const validTags = ['class_serializer', 'doc_url', 'doc_id', 'behavior', 'variants', 'variant', 'shortcut_property',
+    'codegen_names', 'non_exhaustive', 'es_quirk']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()
@@ -671,6 +676,8 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
         type.kind === 'type_alias' && type.type.kind === 'union_of' && type.type.items.length === type.codegenNames.length,
         '@codegen_names must have the number of items as the union definition'
       )
+    } else if (tag === 'es_quirk') {
+      type.esQuirk = value
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on type ${type.name.name}`)
     }
@@ -684,7 +691,8 @@ function hoistPropertyAnnotations (property: model.Property, jsDocs: JSDoc[]): v
   // We want to enforce a single jsDoc block.
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
-  const validTags = ['stability', 'prop_serializer', 'doc_url', 'aliases', 'codegen_name', 'since', 'server_default', 'variant', 'doc_id']
+  const validTags = ['stability', 'prop_serializer', 'doc_url', 'aliases', 'codegen_name', 'since', 'server_default',
+    'variant', 'doc_id', 'es_quirk']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()
@@ -764,6 +772,8 @@ function hoistPropertyAnnotations (property: model.Property, jsDocs: JSDoc[]): v
     } else if (tag === 'variant') {
       assert(jsDocs, value === 'container_property', `Unknown 'variant' value '${value}' on property ${property.name}`)
       property.containerProperty = true
+    } else if (tag === 'es_quirk') {
+      property.esQuirk = value
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on property ${property.name}`)
     }

docs/modeling-guide.md

@@ -397,6 +397,20 @@ export class TermQuery extends QueryBase {
 }
 ```
 
+### Tracking Elasticsearch quirks
+
+There are a few places where Elasticsearch has an uncommon behavior that does not deserve a specific feature in the API specification metamodel. These quirks still have to be captured so that code generators can act on them. The `eq_quirk` jsdoc tag is meant for that, and can be used on type definitions and properties.
+
+```ts
+/**
+ * @es_quirk This enum is a boolean that evolved into a tri-state enum. True and False have
+ *   to be (de)serialized as JSON booleans.
+ */
+enum Foo { true, false, bar }
+```
+
+Code generators should track the `es_quirk` they implement and fail if a new unhandled quirk is present on a type or a property. This behavior allows code generators to be updated whenever a new quirk is identified in the API specification.
+
 ### Additional information
 
 If needed, you can specify additional information on each type with the approariate JSDoc tag.