### Install Project Dependencies

Source: https://github.com/elastic/elasticsearch-specification/blob/main/CONTRIBUTING.md

Installs all necessary project dependencies using `make setup`. This command should be run after Node.js is installed.

```sh
make setup
```

--------------------------------

### Install Node.js with nvm

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Installs Node.js using nvm (Node Version Manager). Ensure nvm is installed first.

```sh
curl -o- https://raw.githubusercontent.com/nvm/nvm/v0.39.7/install.sh | bash
```

--------------------------------

### Example of tech_preview stability

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

An example of marking an API as tech_preview.

```ts
/**
 * @rest_spec_name endpoint.name
 * @availability stack since=1.2.3 stability=tech_preview
 */
```

--------------------------------

### Install nvm

Source: https://github.com/elastic/elasticsearch-specification/blob/main/CONTRIBUTING.md

Installs Node Version Manager (nvm) to manage Node.js versions. Run this script to set up nvm.

```sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
```

--------------------------------

### Install Node.js with nvm

Source: https://github.com/elastic/elasticsearch-specification/blob/main/CONTRIBUTING.md

Installs the Node.js version specified in the .nvmrc file using nvm. Ensure .nvmrc is present before running.

```sh
nvm install
```

--------------------------------

### Container Variant Implementation Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Example of a container variant class.

```ts
/** @variants container */
class FooContainer {
  bar?: BarDefinition
  baz?: BazDefinition
  faz?: FazDefinition
}
```

--------------------------------

### Defining example availability

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Specifying the availability of an example for Stack or Serverless Elasticsearch.

```yaml
availability: [stack]
```

--------------------------------

### Example of experimental stability

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

An example of marking an API as experimental.

```ts
/**
 * @rest_spec_name indices.create
 * @availability stack since=1.0.0 stability=experimental
 */
```

--------------------------------

### Clone Project and Install Dependencies

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Clones the Elasticsearch API Specification repository and installs project dependencies using make.

```sh
git clone https://github.com/elastic/elasticsearch-specification.git

make setup
```

--------------------------------

### Endpoint Naming Examples

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/naming.md

Provides examples of how endpoint names and namespaces map to HTTP request methods and paths, emphasizing lowercase letters and underscores.

```text
`search` -> `POST /_search` and `POST /<index>/_search`
`cluster.health` -> `GET /_cluster/health`
`ccr.get_auto_follow_pattern` -> `GET /_ccr/auto_follow/<name>`
```

--------------------------------

### Install Coreutils on MacOS

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

If the 'realpath' command is not found on MacOS during validation, install the 'coreutils' package using Homebrew.

```shell
brew install coreutils
```

--------------------------------

### Container Property Implementation Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Example of using container_property within a container class.

```ts
/**
 * @variants container
 */
class AggregationContainer {
  // These two field are always available
  /** @variant container_property */
  aggs?: Dictionary<string, AggregationContainer>
  /** @variant container_property */
  meta?: Dictionary<string, UserDefinedValue>
  // Regular container fields. Only one of them can exist at a time.
  adjacency_matrix?: AdjacencyMatrixAggregation
  auto_date_histogram?: AutoDateHistogramAggregation
  avg?: AverageAggregation
  ...
```

--------------------------------

### API request example structure

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Example of a request definition following the OpenAPI 3.0 specification, including summary, method_request, and value fields.

```yaml
summary: Sequence query
method_request: GET /my-data-stream/_eql/search
# type: request
description: >
  Run `GET /my-data-stream/_eql/search` to search for a sequence of events.
  The sequence starts with an event with an `event.category` of `file`, a `file.name` of `cmd.exe`, and a `process.pid` other than `2013`.
  It is followed by an event with an `event.category` of `process` and a `process.executable` that contains the substring `regsvr32`.
  These events must also share the same `process.pid` value.
value: |-
  {
    "query": """
      sequence by process.pid
        [ file where file.name == "cmd.exe" and process.pid != 2013 ]
        [ process where stringContains(process.executable, "regsvr32") ]
    """
  }
```

--------------------------------

### Typed Keys Quirk JSON Output Examples

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

JSON representations for the typed_keys_quirk example.

```json
{
  "name#faz": {
    "prop": "hello world"
  }
}
```

```json
{
  "name#bar": {
    "prop": true
  }
}
```

--------------------------------

### Name Uniqueness Example with JSON

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/naming.md

Shows how leading/trailing underscores and casing can lead to name clashes in generated code, and suggests a more semantic naming approach.

```json
{
  "nodes": {...},
  "_nodes": {...}
}
```

```json
{
  "nodes": {...},
  "node_info": {...}
}
```

--------------------------------

### Typed Keys Quirk Implementation Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Example of using typed_keys_quirk with FooAlias.

```ts
/** @variants typed_keys_quirk */
type FooAlias = Faz | Bar

/** @variant name='faz' */
class Faz {
  prop: string
}

/** @variant name='bar' */
class Bar {
  prop: boolean
}
```

--------------------------------

### Internal Variant Implementation Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Full implementation of internal variants using Foo and Bar classes.

```ts
class Foo {
  type: 'foo',
  prop: string
}

class Bar {
  type: 'bar',
  prop: boolean
}

/** @variants internal tag='type' */
type FooOrBar = Foo | Bar
```

--------------------------------

### Untagged Variant Implementation Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Example of using untagged variants for legacy types.

```ts
export class MyTypeBase<T1, T2, ...> { ... }

export class MyTypeUntyped extends MyTypeBase<UserDefinedValue> {}
export class MyTypeSpecialized1 extends MyTypeBase<int> {}
export class MyTypeSpecialized2 extends MyTypeBase<string> {}
export class MyTypeSpecialized3 extends MyTypeBase<bool> {}

/**
 * @codegen_names untyped, mytype1, mytypet2, mytype3 
 * @variant untagged untyped=_types.MyTypeUntyped
 */
// Note: deserialization depends on value types
export type MyType = MyTypeUntyped | MyTypeSpecialized1 | MyTypeSpecialized2 | MyTypeSpecialized3
```

--------------------------------

### Codegen Names Example 1

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Using @codegen_names for Slices union.

```ts
/** @codegen_names value, computed */
export type Slices = integer | SlicesCalculation
```

--------------------------------

### TypeScript Array Notation Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/style-guide.md

Illustrates the preferred TypeScript array notation. Use the short notation for simple types and the full `Array<>` syntax for complex types like arrays of unions.

```typescript
class Foo {
  bar: string[] // yay
  bar: (string | number)[] // nay
  bar: Array<string | number> // yay
}
```

--------------------------------

### Detailed Elasticsearch Specification JSON Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

An example of the detailed JSON structure for a type definition (Request) and an endpoint (index).

```json
{
  "types": [    {
    "attachedBehaviors": [
      "CommonQueryParameters"
    ],
    "body": {
      "kind": "value",
      "value": {
        "kind": "instance_of",
        "type": {
          "name": "TDocument",
          "namespace": "_global.index"
        }
      }
    },
    "generics": [
      {
        "name": "TDocument",
        "namespace": "_global.index"
      }
    ],
    "inherits": {
      "type": {
        "name": "RequestBase",
        "namespace": "_types"
      }
    },
    "kind": "request",
    "name": {
      "name": "Request",
      "namespace": "_global.index"
    },
    "path": [...],
    "query": [...] 
  }, { 
    "inherits": {
      "type": {
        "name": "WriteResponseBase",
        "namespace": "_types"
      }
    },
    "kind": "response",
    "name": {
      "name": "Response",
      "namespace": "_global.index"
    } 
  }],
  "endpoints": [{
      "accept": [
        "application/json"
      ],
      "contentType": [
        "application/json"
      ],
      "description": "Creates or updates a document in an index.",
      "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html",
      "name": "index",
      "request": {
        "name": "Request",
        "namespace": "_global.index"
      },
      "requestBodyRequired": true,
      "response": {
        "name": "Response",
        "namespace": "_global.index"
      },
      "since": "0.0.0",
      "stability": "stable",
      "urls": [...],
      "visibility": "public"
    }]
}
```

--------------------------------

### Valid and Invalid Name Examples

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/naming.md

Illustrates correct and incorrect naming conventions, particularly regarding the use of numeric characters and casing.

```text
DO: `name`
DONT: `1name`
```

--------------------------------

### Explicit Unit Specification Examples

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/data-modelling.md

Demonstrates the correct ways to specify values with units in Elasticsearch API requests, including using suffixes or a dedicated unit property.

```json
{"took_in_millis": 3}
```

```json
{"took": "3ms"}
```

```json
{"took": {"value": 3, "unit": "ms"}}
```

--------------------------------

### Run ESLint on Specification

Source: https://github.com/elastic/elasticsearch-specification/blob/main/validator/README.md

Execute the ESLint linter on the specification project to identify and report any rule violations. Ensure you are in the 'specification/' directory and have installed dependencies.

```bash
npm run lint
```

--------------------------------

### Codegen Names Example 2

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Using @codegen_names for TermsInclude union.

```ts
/** @codegen_names regexp, terms, partition */
export type TermsInclude = string | string[] | TermsPartition
```

--------------------------------

### Codegen Names Example 3

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Using @codegen_names for MessageContent union.

```ts
/** @codegen_names string, object */
export type MessageContent = string | Array<ContentObject>
```

--------------------------------

### Duration and Byte Size Units in Elasticsearch

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/data-modelling.md

Examples of how to specify duration and byte size values with explicit units in Elasticsearch API requests.

```json
{"start_date_in_millis": 1652296510000}
```

```json
{"duration_in_millis": 10}
```

--------------------------------

### TypeScript Union Type Alias Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/style-guide.md

Demonstrates the preferred way to use union types in TypeScript definitions by creating a type alias. Avoids inline union types for better readability.

```typescript
// nay
class Foo {
  id: string | number
}

// yay
class Foo {
  id: Id
}
type Id = string | number
```

--------------------------------

### Date Format Specification in Elasticsearch

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/data-modelling.md

Example of specifying a date format for a field in an Elasticsearch API request. This ensures correct interpretation and validation of date values.

```yaml
{"type": "date", "format": "yyyy-MM-dd HH:mm:ss"}
```

--------------------------------

### Internal Variant Definition Example

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Defines a class with an internal variant type field.

```ts
class Foo {
  type: 'foo', // 'type' is the variant
  prop: string
}
```

--------------------------------

### Run All Validations with Make

Source: https://github.com/elastic/elasticsearch-specification/blob/main/validator/README.md

From the repository's root directory, use the 'make' command to run the linter along with other validation checks. This provides a comprehensive validation of the specification.

```bash
make setup && make validate
```

--------------------------------

### Initialize and Compile Agentic Workflow

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/spec-drift-check.md

Commands to initialize the agentic workflow environment and compile the workflow definition. Use --no-mcp for initialization if not using MCP.

```sh
gh aw init --no-mcp
gh aw compile spec-drift
```

--------------------------------

### Copilot BYOK Configuration via LiteLLM

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/spec-drift-check.md

Sets up the Copilot engine to use Bring-Your-Own-Key (BYOK) mode through Elastic's LiteLLM OpenAI-compatible endpoint. Ensure the LITELLM_API_KEY secret is configured.

```yaml
engine:
  id: copilot
  env:
    COPILOT_PROVIDER_BASE_URL: "https://elastic.litellm-prod.ai/v1"
    COPILOP_MODEL: "llm-gateway/claude-sonnet-4-6"
    COPILOT_PROVIDER_API_KEY: "${{ secrets.LITELLM_API_KEY }}"
    COPILOT_PROVIDER_TYPE: "openai"
```

--------------------------------

### Run Contribution Tasks

Source: https://github.com/elastic/elasticsearch-specification/blob/main/CONTRIBUTING.md

Executes tasks required for contributing to the specification, including style checks and output generation. Run this before committing changes.

```sh
make contrib
```

--------------------------------

### Make Targets Overview

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Provides a list of available make targets for interacting with the Elasticsearch API Specification project, including validation, generation, and transformation commands.

```makefile
Usage:
  make <target>
  validate         Validate a given endpoint request or response
  validate-no-cache  Validate a given endpoint request or response without local cache
  generate         Generate the output spec
  compile          Compile the specification
  license-check    Add the license headers to the files
  license-add      Add the license headers to the files
  spec-format-check  Check specification formatting rules
  spec-format-fix  Format/fix the specification according to the formatting rules
  spec-dangling-types  Generate the dangling types report
  setup            Install dependencies for contrib target
  clean-dep        Clean npm dependencies
  transform-expand-generics  Create a new schema with all generics expanded
  transform-to-openapi  Generate the OpenAPI definition from the compiled schema
  filter-for-serverless  Generate the serverless version from the compiled schema
  dump-routes      Create a new schema with all generics expanded
  contrib          Pre contribution target
  lint-docs        Lint the OpenAPI documents
  lint-docs-serverless  Lint only the serverless OpenAPI document
  help             Display help
```

--------------------------------

### Define Request and Response types

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Create separate files for request and response definitions, naming the files after the types they contain.

```typescript
// IndexRequest.ts
interface Request {}
```

```typescript
// IndexResponse.ts
class Response {}
```

--------------------------------

### Adding property descriptions

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Use JSDoc comments to provide descriptions for types and properties.

```ts
class Foo {
  bar: string
  /** You can baz! */
  baz: string
  faz: string
}
```

--------------------------------

### Underscore Usage for Readability

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/naming.md

Demonstrates the correct use of underscores to separate words in API names for improved readability, contrasting with incorrect hyphenation or lack of separation.

```text
DO: `searchable_snapshot`
DON'T: `search_able_snapshot` (even if it were "search-able snapshot" this isn't correct)
DON'T: `searchablesnapshot`
DON'T: `searchable_snap_shot` ("snapshot" is one word)
```

--------------------------------

### Generate OpenAPI for Docs

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Generates OpenAPI files specifically for documentation purposes, followed by applying necessary fixes.

```sh
make transform-to-openapi-for-docs

make overlay-docs
```

--------------------------------

### Re-download Recordings for Validation

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Command to re-download test recordings if needed, for a specific API, type, and branch.

```sh
make validate-no-cache api=xpack.info type=request branch=main
```

--------------------------------

### Clone Repositories for Validation

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Commands to clone the necessary repositories for validating the Elasticsearch specification.

```sh
git clone https://github.com/elastic/elasticsearch-specification.git
git clone https://github.com/elastic/clients-flight-recorder.git
```

--------------------------------

### Implement CommonQueryParameters

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/behaviors.md

Implements a set of common query parameters supported by most APIs. Clients should define support, with `error_trace` and `pretty` recommended.

```typescript
class RequestBase implements CommonQueryParameters {}
```

--------------------------------

### Pull Latest Changes for Client Flight Recorder

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Navigate to the client-flight-recorder directory and pull the latest changes using git. This is often necessary when encountering validation issues on GitHub that work locally.

```shell
cd client-flight-recorder
git pull
```

--------------------------------

### Defining @index_privileges

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Specifies index security prerequisites as a comma-separated list.

```ts
/**
 * @rest_spec_name indices.create
 * @availability stack since=0.0.0 stability=stable
 * @index_privileges create_index, manage
 */
export interface Request extends RequestBase {
 ...
}
```

--------------------------------

### Implement CommonCatQueryParameters

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/behaviors.md

Implements common query parameters specifically for Cat APIs. These are listed explicitly as behaviors as they can affect the request structure.

```typescript
class CatRequestBase extends RequestBase implements CommonCatQueryParameters {}
```

--------------------------------

### Defining @doc_url

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Specifies a direct documentation URL for a parameter or definition. Use @doc_id instead to reduce broken links.

```ts
class Foo {
  bar: string
  /** @doc_url http://localhost:9200 */
  baz?: string
  faz: string
}
```

--------------------------------

### Nesting and Dots Equivalence

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/naming.md

Illustrates how dotted notation for nested structures is equivalent to using nested JSON objects, with a note that language clients only support nested objects.

```json
{
  "index.settings.number_of_shards": 1
}
```

```json
{
  "index": {
    "settings": {
      "number_of_shards": 1
    }
  }
}
```

--------------------------------

### Validate Multiple API Request and Response Types

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Command to validate multiple API request and response types (e.g., xpack.info, search) against a specified branch.

```sh
# this will validate the xpack.info and search request and response types against the 8.15 branch
make validate api=xpack.info,search branch=8.15
```

--------------------------------

### Container Property Annotation Syntax

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Syntax for distinguishing container properties from variants.

```ts
/** @variant container_property */
```

--------------------------------

### Defining @ext_doc_id

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Links a definition to an external documentation URL. This link is included in the OpenAPI output.

```ts
/**
 * @variants container
 * @non_exhaustive
 * @ext_doc_id query-dsl
 */
export class QueryContainer {
  ...
}
```

```csv
query-dsl,/guide/en/example
```

--------------------------------

### Identify Type by Kind in JSON

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/schema-structure.md

Shows a JSON object representing a type, including its kind, name, properties, and source file location, useful for schema introspection.

```json
{
  "kind": "interface",
  "name": {
    "name": "User",
    "namespace": "security._types"
  },
  "properties": [...],
  "specLocation": "security/_types/User.ts#L22-L29"
}
```

--------------------------------

### Importing a Rule in ESM Format

Source: https://github.com/elastic/elasticsearch-specification/blob/main/validator/README.md

When using the ESM module format, ensure you include the file extension in your import statements.

```javascript
import myRule from './rules/my-rule.js' // not ./rules/my-rule
```

--------------------------------

### Defining @cluster_privileges

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Specifies cluster security prerequisites as a comma-separated list.

```ts
/**
 * @rest_spec_name cluster.state
 * @availability stack since=1.3.0 stability=stable
 * @cluster_privileges monitor, manage
 */
export interface Request extends RequestBase {
 ...
}
```

--------------------------------

### Compile Agentic Workflow with Validation

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/spec-drift-check.md

Compiles the agentic workflow and outputs validation information in JSON format without emitting the lock file. Useful for checking workflow syntax and configuration.

```sh
gh aw compile spec-drift --no-emit --json
```

--------------------------------

### Mapping path and query parameters as CSV

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Mapping parameters that accept either a string or comma-separated values using a type alias.

```ts
export type MyAlias = string | string[]

path_parts: {
    param_name?: MyAlias
}
query_parameters: {
    param_name?: MyAlias
}
```

--------------------------------

### Container Variant Syntax

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Syntax for defining a container variant.

```ts
/** @variants container */
```

--------------------------------

### Response definition template

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Template for defining a response body. Response definitions must be named 'Response' and defined after the request definition.

```ts
class Response {
  body: {

  }
}
```

--------------------------------

### Generate OpenAPI Representation

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Generates the OpenAPI representation from the compiled schema after following the steps to generate the JSON representation.

```sh
make transform-to-openapi
```

--------------------------------

### Request definition with generics

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Template for request definitions that require one or more generics.

```typescript
 /*
 * @rest_spec_name endpoint.name
 * @availability stack since=1.2.3 stability=stable|beta|experimental|tech_preview
 */
interface Request<Generic> extends RequestBase {
  urls: [
    {
      path: "/path/with/{parts}"
      methods: ["POST"]
    }
  ]
  path_parts: {

  }
  query_parameters: {

  }
  body: {

  }
}
```

--------------------------------

### Request definition template

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Standard template for defining an API request, including required JSDoc tags and top-level keys.

```typescript
 /*
 * @rest_spec_name endpoint.name
 * @availability stack since=1.2.3 stability=stable|beta|experimental|tech_preview
 */
interface Request extends RequestBase {
  urls: [
    {
      path: "/path/with/{parts}"
      methods: ["POST"]
    }
  ]
  path_parts: {

  }
  query_parameters: {

  }
  body: {

  }
}
```

--------------------------------

### Syntax for stability in @availability

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

The syntax for adding a stability level to an availability annotation.

```ts
/** @availability stack since=<version> stability=<value> */
```

--------------------------------

### Response definition with generics

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Template for a response definition that utilizes one or more generics.

```ts
class Response<Generic> {
  body: {
    key: Generic
  }
}
```

--------------------------------

### Internal Variant Configuration Syntax

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Syntax for configuring the parent type with the @variants tag.

```ts
/** @variants internal tag='<field-name>' */
```

--------------------------------

### Define flavor-specific availability

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Demonstrates how to restrict fields to specific Elasticsearch flavors or indicate availability in both.

```ts
export class Example {
  /**
   * This field is available in both (default when there aren't any annotations).
   */
  fieldBoth1: integer

  /**
   * This field is available in both flavors and is explicitly annotated.
   * @availability stack
   * @availability serverless
   */ 
  fieldBoth2: integer

  /**
   * This field is only available on Serverless Elasticsearch.
   * @availability serverless
   */
  fieldServerlessOnly: integer

  /**
   * This field is only available on Stack Elasticsearch.
   * @availability stack
   */
  fieldStackOnly: integer
}
```

--------------------------------

### JSON Code Style Configuration

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/style-guide.md

These are the code formatting rules enforced for JSON files within the specification. Automatic application is available via `make spec-format-fix`.

```json
{
  "trailingComma": "none",
  "tabWidth": 2,
  "useTabs": false,
  "semi": false,
  "singleQuote": true,
  "quoteProps": "as-needed",
  "bracketSpacing": true,
  "endOfLine": "lf"
}
```

--------------------------------

### Defining API exceptions

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/add-new-api.md

Using the exceptions key to document non-standard error response structures.

```ts
class Response {
  body: SuccessResponseBodyType
  exceptions: [
    {
      /**
       * A brief description of the exception.
       */
      statusCodes: [404]
      body: NotFoundException
    }
  ]
}
```

--------------------------------

### Repository Access Configuration

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/spec-drift-check.md

Configures the allowed repositories and minimum integrity level for the GitHub Agentic Workflow. Use 'approved' integrity for workflows that can create issues.

```yaml
strict: true
timeout-minutes: 45

tools:
  github:
    mode: gh-proxy
    allowed-repos:
      - elastic/elasticsearch
      - elastic/elasticsearch-specification
    min-integrity: approved
```

--------------------------------

### Validate Elasticsearch API Definition

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/validation-example.md

Run the validation process for a specific API definition. Ensure you have the necessary build tools and dependencies set up.

```sh
make validate api=index branch=main
```

--------------------------------

### Schema Root Structure

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/schema-structure.md

The root of the schema.json file contains metadata about the specification, including license information and the title, along with arrays for endpoints and types.

```json
{
  "_info": {
    "license": {
      "name": "Apache 2.0",
      "url": "https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE"
    },
    "title": "Elasticsearch Request & Response Specification"
  },
  "endpoints": [...],
  "types": [...] 
}
```

--------------------------------

### Defining @doc_tag

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Groups similar endpoints in the API documentation using an OpenAPI tag.

```ts
/**
 * @rest_spec_name api
 * @doc_tag my tag
 */
class Request {
  ...
}
```

--------------------------------

### Use Stringified Behavior

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Apply the Stringified behavior to fields that are represented as strings in JSON output but should maintain their original format for input.

```ts
export class IndexSettings {
  number_of_shards?: Stringified<integer>
  number_of_replicas?: Stringified<integer>
  hidden?: Stringified<boolean>
}
```

--------------------------------

### Identify Type by Name in TypeScript

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/schema-structure.md

Defines a TypeScript class 'User' and illustrates how its name and namespace are represented in a JSON object for identification.

```typescript
// file: specification/security/_types/User.ts
export class User {
  email?: string | null
  full_name?: Name | null
  metadata: Metadata
  roles: string[]
  username: Username
  enabled: boolean
}
```

```json
{
  "name": "User",
  "namespace": "security._types"
}
```

--------------------------------

### Validate Specific API Request Type

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Command to validate a specific API request type (e.g., xpack.info) against the main branch.

```sh
cd elasticsearch-specification
# this will validate the xpack.info request type against the main branch of Elasticsearch
make validate api=xpack.info type=request branch=main
```

--------------------------------

### TypeScript Index Request Definition Test

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/validation-example.md

This TypeScript code snippet demonstrates a test case for the IndexRequest definition, used to verify type compatibility. It utilizes `expectAssignable` from 'tsd' for type checking.

```ts
import { expectAssignable } from 'tsd'
import * as T from '../node_modules/elasticsearch-client-specification/output/typescript/types'
expectAssignable<T.IndexRequest<any>>({
  "index": "test_1",
  "id": 1,
  "op_type": "create",
  "body": {
    "foo": "bar"
  }
})
```

--------------------------------

### Defining @doc_id

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Links a request to a documentation URL defined in the CSV table. This link is not included in OpenAPI output.

```ts
/**
 * @rest_spec_name api
 * @doc_id foobar
 */
class Request {
  ...
}
```

```csv
foobar,/guide/en/example
```

--------------------------------

### Representing Special Floating-Point Values as Strings

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/data-modelling.md

When dealing with float32 or float64 types, special values like negative zero, NaN, and infinity should be encoded as JSON strings for maximum portability. Ensure precise casing and include the decimal point.

```json
"-0.0"
```

```json
"NaN"
```

```json
"Infinity"
```

```json
"+Infinity"
```

```json
"-Infinity"
```

--------------------------------

### Modeling Object Variants with Internal Tagging

Source: https://github.com/elastic/elasticsearch-specification/blob/main/api-design-guidelines/data-modelling.md

Use internal tagging, typically a 'type' property, to model object variants. This method is common and generally preferred for its simplicity in identifying the variant.

```yaml
{
  "type": "snowball",
  "stopwords": ["if", "and", "but"]
}
```

--------------------------------

### Defining @deprecated

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Marks an endpoint or property as deprecated, including the version and an optional description.

```ts
class Foo {
  bar: string
  /** @deprecated 7.0.0 */
  baz?: string
  faz: string
}
```

```ts
class Foo {
  bar: string
  /** @deprecated 7.0.0 'baz' has been deprecated, use 'bar' instead */
  baz?: string
  faz: string
}
```

--------------------------------

### Defining @server_default for arrays

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Use JavaScript array syntax when specifying a default value for an array property.

```ts
class Foo {
  bar: string
  /** @server_default ['hello'] */
  baz?: string[]
  faz: string
}
```

--------------------------------

### Validate API Request and Response Types for a Specific Branch

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Command to validate both request and response types for a specific API against a particular branch (e.g., 8.15).

```sh
# this will validate the xpack.info request and response types against the 8.15 branch
make validate api=xpack.info branch=8.15
```

--------------------------------

### Array Type Syntax

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

Represents an array of a given value using either generic or short syntax.

```ts
// generics syntax
property: Array<string>

// short syntax
property: string[]
```

--------------------------------

### Index API Endpoint

Source: https://github.com/elastic/elasticsearch-specification/blob/main/README.md

Details for the Index API endpoint, used for creating or updating documents in an index.

```APIDOC
## POST /_doc/{index}

### Description
Creates or updates a document in an index.

### Method
POST

### Endpoint
/_doc/{index}

### Parameters
#### Path Parameters
- **index** (string) - Required - The name of the index (required)

#### Query Parameters
- **wait_for_active_shards** (string) - Optional - Sets the number of active shards to wait for on the relevant shards before getting the response.
- **op_type** (string) - Optional - Specifies the operation type. Can be `index` or `create`.
- **refresh** (string) - Optional - If `true` then the affected shards will be refreshed before exiting.
- **routing** (string) - Optional - Specific routing value.
- **timeout** (string) - Optional - Explicit operation timeout.
- **version** (long) - Optional - Explicit version number for optimistic concurrency control
- **version_type** (string) - Optional - Specific version type

### Request Body
- **body** (object) - Required - The document to index.

### Request Example
```json
{
  "example": "{\"field\": \"value\"}"
}
```

### Response
#### Success Response (200)
- **_index** (string) - The name of the index.
- **_id** (string) - The ID of the document.
- **_version** (long) - The version number of the document.
- **result** (string) - The result of the operation (e.g., 'created', 'updated').
- **_shards** (object) - Information about the shards involved in the operation.
  - **total** (long) - The total number of shards.
  - **successful** (long) - The number of successful shards.
  - **failed** (long) - The number of failed shards.
- **_seq_no** (long) - The sequence number of the last operation.
- **_primary_term** (long) - The primary term of the last operation.

#### Response Example
```json
{
  "_index": "my-index",
  "_id": "my-document-id",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 0,
  "_primary_term": 1
}
```
```

--------------------------------

### Binary Type Schema Definition

Source: https://github.com/elastic/elasticsearch-specification/blob/main/docs/modeling-guide.md

The resulting schema definition for the MapboxVectorTiles binary type alias.

```json
{
  "kind": "type_alias",
  "name": {
    "name": "MapboxVectorTiles",
    "namespace": "_types"
  },
  "type": {
    "kind": "instance_of",
    "type": {
      "name": "binary",
      "namespace": "internal"
    }
  }
}
```