elasticsearch-shared-overlays.yaml

# Overlays that are applicable to both Elasticsearch and Elasticsearch Serverless OpenAPI documents
overlay: 1.0.0
info:
  title: Overlays for changes that apply to both Elasticsearch and Elasticsearch Serverless OpenAPI documents
  version: 0.0.1
actions:
# Add an alphabetically sorted list of tags
  - target: '$'
    description: Add document-level tags sorted by display name
    update:
      tags:
      # A
        - name: autoscaling
          x-displayName: Autoscaling
      # B
        - name: analytics
          x-displayName: Behavioral analytics
      # C 
        - name: cat
          x-displayName: Compact and aligned text (CAT)
          description: >
            The compact and aligned text (CAT) APIs aim are intended only for human consumption using the Kibana console or command line.
            They are not intended for use by applications.
            For application consumption, it's recommend to use a corresponding JSON API.
            
            All the cat commands accept a query string parameter `help` to see all the headers and info they provide, and the `/_cat` command alone lists all the available commands.
        - name: cluster
          x-displayName: Cluster
        - name: health_report
          x-displayName: Cluster - Health
        - name: connector
          x-displayName: Connector
          description: >
            The connector and sync jobs APIs provide a convenient way to create and manage Elastic connectors and sync jobs in an internal index.
            
            Connectors are Elasticsearch integrations that bring content from third-party data sources, which can be deployed on Elastic Cloud or hosted on your own infrastructure:
            
            * Native connectors are a managed service on Elastic Cloud
            * Connector clients are self-managed on your infrastructure
            
            This API provides an alternative to relying solely on Kibana UI for connector and sync job management. The API comes with a set of validations and assertions to ensure that the state representation in the internal index remains valid.
          externalDocs:
            url: https://www.elastic.co/guide/en/enterprise-search/current/connectors-tutorial-api.html
            description: To get started with Connector APIs, check out the tutorial.
        - name: ccr
          x-displayName: Cross-cluster replication
      # D
        - name: data stream
          x-displayName: Data stream
          externalDocs:
            description: Data stream overview 
            url: https://www.elastic.co/guide/en/elasticsearch/reference/master/data-streams.html
        - name: document
          x-displayName: Document
          externalDocs:
            description: Reading and writing documents
            url: https://www.elastic.co/guide/en/elasticsearch/reference/master/docs-replication.html
        - name: mget
          x-displayName: Document - Multi get
        - name: mtermvectors
          x-displayName: Document - Multi term vectors
        - name: delete_by_query_rethrottle
          x-displayName: Document - Rethrottle delete by query
        - name: update_by_query_rethrottle
          x-displayName: Document - Rethrottle update by query
      # E  
        - name: enrich
          x-displayName: Enrich
        - name: eql
          x-displayName: EQL
          description: >
            Event Query Language (EQL) is a query language for event-based time series data, such as logs, metrics, and traces.
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/eql.html
            description: EQL search
        - name: esql
          x-displayName: ES|QL
          description: >
            The Elasticsearch Query Language (ES|QL) provides a powerful way to filter, transform, and analyze data stored in Elasticsearch, and in the future in other runtimes.
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/esql.html
            description: ES|QL overview and tutorials
      # F
        - name: features
          description: The feature APIs enable you to introspect and manage features provided by Elasticsearch and Elasticsearch plugins.
          x-displayName: Features
        - name: fleet
          x-displayName: Fleet
      # G
        - name: graph
          x-displayName: Graph explore
          description: >
            The graph explore API enables you to extract and summarize information about the documents and terms in an Elasticsearch data stream or index.
          externalDocs:
            url: https://www.elastic.co/guide/en/kibana/current/xpack-graph.html
            description: Getting started with Graph
      # I
        - name: indices
          x-displayName: Index
          description: >
            Index APIs enable you to manage individual indices, index settings, aliases, mappings, and index templates.
        - name: dangling_indices
          x-displayName: Index - Import dangling index
        - name: ilm
          x-displayName: Index lifecycle management
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html
            description: Manage the index lifecycle
        - name: inference
          x-displayName: Inference
          description: >
            Inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio or Hugging Face.
            For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models.
            However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
        - name: info
          x-displayName: Info
        - name: ingest
          x-displayName: Ingest
          description: Ingest APIs enable you to manage tasks and resources related to ingest pipelines and processors.
      # L  
        - name: license
          x-displayName: Licensing
          description: Licensing APIs enable you to manage your licenses.
        - name: logstash
          x-displayName: Logstash
          description: >
            Logstash APIs enable you to manage pipelines that are used by Logstash Central Management.
          externalDocs:
            url: https://www.elastic.co/guide/en/logstash/current/logstash-centralized-pipeline-management.html
            description: Centralized pipeline management
      # M
        - name: ml
          x-displayName: Machine learning
        - name: ml anomaly
          x-displayName: Machine learning anomaly detection
          # description:
          externalDocs:
            url: https://www.elastic.co/guide/en/machine-learning/master/ml-ad-finding-anomalies.html
            description: Finding anomalies
        - name: ml data frame
          x-displayName: Machine learning data frame analytics
          # description:
          externalDocs:
            url: https://www.elastic.co/guide/en/machine-learning/master/ml-dfa-overview.html
            description: Data frame analytics overview
        - name: ml trained model
          x-displayName: Machine learning trained model
          # description:
          externalDocs:
            url: https://www.elastic.co/guide/en/machine-learning/master/ml-nlp-overview.html
            description: Natural language processing overview
        - name: migration
          x-displayName: Migration
        - name: monitoring
          x-displayName: Monitoring
      # N
        - name: shutdown
          x-displayName: Node lifecycle
      # Q
        - name: query_rules
          x-displayName: Query rules
          description: >
            Query rules enable you to configure per-query rules that are applied at query time to queries that match the specific rule.
            Query rules are organized into rulesets, collections of query rules that are matched against incoming queries.
            Query rules are applied using the rule query.
            
            If a query matches one or more rules in the ruleset, the query is re-written to apply the rules before searching.
            This allows pinning documents for only queries that match a specific term.
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-rule-query.html
            description: Rule query
      # R
        - name: rollup
          x-displayName: Rollup
      # S
        - name: script
          x-displayName: Script
        - name: get_script_context
          x-displayName: Script - Get contexts
        - name: get_script_languages
          x-displayName: Script - Get languages
        - name: search
          x-displayName: Search
        - name: msearch
          x-displayName: Search - Multi search
        - name: scroll
          x-displayName: Search - Scroll
        - name: terms_enum
          x-displayName: Search - Terms enum
        - name: search_application
          x-displayName: Search application
        - name: searchable_snapshots
          x-displayName: Searchable snapshots
        - name: security
          x-displayName: Security
        - name: ssl
          x-displayName: Security - SSL
        - name: snapshot
          x-displayName: Snapshot and restore
          description: >
            Snapshot and restore APIs enable you to set up snapshot repositories, manage snapshot backups, and restore snapshots to a running cluster.
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-restore.html
            description: Snapshot and restore
        - name: slm
          x-displayName: Snapshot lifecycle management
          description: >
            Snapshot lifecycle management (SLM) APIs enable you to set up policies to automatically take snapshots and control how long they are retained.
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshots-take-snapshot.html
            description: Create a snapshot
        - name: sql
          x-displayName: SQL
          description: >
            Elasticsearch's SQL APIs enable you to run SQL queries on Elasticsearch indices and data streams.
          externalDocs:
            url: https://www.elastic.co/guide/en/elasticsearch/reference/current/xpack-sql.html
            description: An overview and tutorials for the Elasticsearch SQL features
        - name: synonyms
          x-displayName: Synonyms
          description: >
            The synonyms management API provides a convenient way to define and manage synonyms in an internal system index.
            Related synonyms can be grouped in a "synonyms set".
            Create as many synonym sets as you need.
      # T  
        - name: tasks
          x-displayName: Task management
        - name: text_structure
          x-displayName: Text structure
        - name: transform
          x-displayName: Transform
      # U
        - name: xpack
          x-displayName: Usage
      # W
        - name: watcher
          x-displayName: Watcher
# Add x-model and/or abbreviate schemas that should point to other references
  - target: "$.components['schemas']['_types.query_dsl:QueryContainer']"
    description: Add x-model and updated externalDocs for the QueryContainer object
    update:
      x-model: true
      externalDocs:
        url: https://www.elastic.co/guide/en/elasticsearch/reference/master/query-dsl.html
        description: Query domain specific language (DSL) reference
  - target: "$.components['schemas']['_types.analysis:CharFilter'].oneOf"
    description: Remove existing oneOf definition for CharFilter
    remove: true
  - target: "$.components['schemas']['_types.analysis:CharFilter']"
    description: Simplify CharFilter definition
    update:
      x-model: true
      description: >
        Character filters that are used to preprocess characters before they are passed to the tokenizer.
      externalDocs:
        url: https://www.elastic.co/guide/en/elasticsearch/reference/master/analysis-charfilters.html
        description: Character filters reference
  - target: "$.components['schemas']['_types.analysis:Tokenizer'].oneOf"
    description: Remove existing oneOf definition for tokenizer
    remove: true
  - target: "$.components['schemas']['_types.analysis:Tokenizer']"
    description: Simplify tokenizer definition
    update:
      x-model: true
      description: >
        A tokenizer to use to convert text into tokens.
      externalDocs:
        url: https://www.elastic.co/guide/en/elasticsearch/reference/master/analysis-tokenizers.html
        description: Tokenizer reference
  - target: "$.components['schemas']['_types.analysis:TokenFilter'].oneOf"
    description: Remove existing oneOf definition for tokenfilter
    remove: true
  - target: "$.components['schemas']['_types.analysis:TokenFilter']"
    description: Simplify tokenfilter definition
    update:
      x-model: true
      description: >
        Token filters that are applied after the tokenizer.
      externalDocs:
        url: https://www.elastic.co/guide/en/elasticsearch/reference/master/analysis-tokenfilters.html
        description: Token filter reference
  - target: "$.components['schemas']['security._types:RoleTemplateScript']"
    description: Add x-model where recommended by Bump.sh
    update:
      x-model: true
      externalDocs:
        description: Templating a role query
        url: https://www.elastic.co/guide/en/elasticsearch/reference/master/field-and-document-access-control.html#templating-role-query
# Annotate items that are not shown in Bump.sh due to depth limits
  # These hopefully can be fixed by adding branch levels in Bump.sh since the info doesn't exist elsewhere
  - target: "$.components['schemas']['ml._types:TrainedModelConfigMetadata'].properties"
    description: Add x-model to trained_model_configs > metadata > total_feature_importance
    update:
      total_feature_importance:
        x-model: true
  - target: "$.components['schemas']['ml._types:Detector'].properties"
    description: Add x-model to anomaly detection job > analysis_config > detectors > custom_rules
    update:
      custom_rules:
        x-model: true
  - target: "$.components['schemas']['ml._types:DetectorRead'].properties"
    description: Add x-model to anomaly detection jobs > analysis_config > detectors > custom_rules
    update:
      custom_rules:
        x-model: true
  - target: "$.components['schemas']['ml.put_trained_model:TargetMeanEncodingPreprocessor'].properties"
    description: Add x-model to data frame analytics job > analysis> classification > feature_processors > target_mean_encoding > target_map
    update:
      target_map:
        x-model: true
# Examples
  - target: "$.components['requestBodies']['async_search.submit']"
    description: "Add example for asynch search submit request"
    update: 
      content:
        application/json:
          examples:
            asyncSearchSubmitRequestExample1:
              $ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json"
  - target: "$.components['responses']['async_search.submit#200']"
    description: "Add example for asynch search submit response"
    update: 
      content:
        application/json:
          examples:
            asyncSearchSubmitResponseExample1:
              $ref: "../../specification/async_search/submit/AsyncSearchSubmitResponseExample1.json"
  - target: "$.paths['/_transform/{transform_id}']['put']"
    description: "Add examples for create transform operation"
    update: 
      requestBody: 
        content: 
          application/json: 
            examples: 
              createTransformRequestExample1: 
                $ref: "../../specification/transform/put_transform/PutTransformRequestExample1.json"
              createTransformRequestExample2:
                $ref: "../../specification/transform/put_transform/PutTransformRequestExample2.json"
      responses:
        200:
          content:
            application/json:
              examples:
                createTransformResponseExample1:
                  $ref: "../../specification/transform/put_transform/PutTransformResponseExample1.json"
  - target: "$.components['requestBodies']['transform.preview_transform']"
    description: "Add examples for preview transform operation"
    update: 
      content: 
        application/json: 
          examples: 
            previewTransformRequestExample1: 
              $ref: "../../specification/transform/preview_transform/PreviewTransformRequestExample1.json"
  - target: "$.components['responses']['transform.preview_transform#200']"
    description: "Add examples for preview transform operation"
    update: 
      content:
        application/json:
          examples:
            previewTransformResponseExample1:
              $ref: "../../specification/transform/preview_transform/PreviewTransformResponseExample1.json"
  - target: "$.paths['/_transform/{transform_id}/_update']['post']"
    description: "Add examples for update transform operation"
    update: 
      requestBody: 
        content: 
          application/json: 
            examples: 
              updateTransformRequestExample1: 
                $ref: "../../specification/transform/update_transform/UpdateTransformRequestExample1.json"
      responses:
        200:
          content:
            application/json:
              examples:
                updateTransformResponseExample1:
                  $ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json"
  - target: "$.paths['/_eql/search/status/{id}']['get']"
    description: "Add examples for get async EQL status operation"
    update: 
      responses:
        200:
          content:
            application/json:
              examples:
                eqlGetStatusResponseExample1:
                  $ref: "../../specification/eql/get_status/EqlGetStatusResponseExample1.json"
  - target: "$.components['requestBodies']['eql.search']"
    description: "Add examples for EQL search operation"
    update: 
      content: 
        application/json: 
          examples: 
            eqlSearchRequestExample1: 
              $ref: "../../specification/eql/search/EqlSearchRequestExample1.json"
            eqlSearchRequestExample2: 
              $ref: "../../specification/eql/search/EqlSearchRequestExample2.json"
  - target: "$.components['reponses']['eql.search#200']"
    description: "Add examples for EQL search operation"
    update: 
      content:
        application/json:
          examples:
            eqlSearchResponseExample2:
              $ref: "../../specification/eql/search/EqlSearchResponseExample2.json"
  - target: "$.paths['/_query']['post']"
    description: "Add examples for ES|QL query operation"
    update: 
      requestBody: 
        content: 
          application/json: 
            examples: 
              esqlQueryRequestExample1: 
                $ref: "../../specification/esql/query/EsqlQueryApiRequestExample1.json"
  - target: "$.components['requestBodies']['graph.explore']"
    description: "Add example for graph explore request"
    update: 
      content:
        application/json:
          examples:
            graphExploreRequestExample1:
              $ref: "../../specification/graph/explore/graphExploreRequestExample1.json"
  - target: "$.paths['/{index}/_block/{block}']['put']"
    description: "Add examples for add index block operation"
    update: 
      responses:
        200:
          content:
            application/json:
              examples:
                indicesAddBlockResponseExample1:
                  $ref: "../../specification/indices/add_block/IndicesAddBlockResponseExample1.yaml"
  - target: "$.components['requestBodies']['indices.analyze']"
    description: "Add example for analyze API request"
    update: 
      content:
        application/json:
          examples:
            indicesAnalyzeRequestExample1:
              $ref: "../../specification/indices/analyze/indicesAnalyzeRequestExample1.yaml"
  - target: "$.paths['/{index}']['put']"
    description: "Add examples for create index request"
    update: 
      requestBody:
        content:
          application/json:
            examples:
              indicesCreateRequestExample1:
                $ref: "../../specification/indices/create/indicesCreateRequestExample1.yaml"
              indicesCreateRequestExample2:
                $ref: "../../specification/indices/create/indicesCreateRequestExample2.yaml"
  - target: "$.paths['/_data_stream/{name}/_lifecycle']['delete']"
    description: "Add example for delete data stream lifecycle response"
    update: 
      responses:
        200:
          content:
            application/json:
              examples:
                indicesDeleteDataLifecycleResponseExample1:
                  $ref: "../../specification/indices/delete_data_lifecycle/IndicesDeleteDataLifecycleResponseExample1.yaml"
  - target: "$.paths['/_data_stream/{name}/_lifecycle']['get']"
    description: "Add example for get data stream lifecycle response"
    update: 
      responses:
        200:
          content:
            application/json:
              examples:
                indicesGetDataLifecycleResponseExample1:
                  $ref: "../../specification/indices/get_data_lifecycle/IndicesGetDataLifecycleResponseExample1.yaml"
  - target: "$.components['responses']['indices.get_data_stream#200']"
    description: "Add example for get data stream response"
    update: 
      content:
        application/json:
          examples:
            indicesGetDataStreamResponseExample:
              $ref: "../../specification/indices/get_data_stream/indicesGetDataStreamResponseExample1.yaml"
  - target: "$.paths['/_data_stream/{name}/_lifecycle']['put']"
    description: "Add examples update data stream lifecycle request and response"
    update: 
      requestBody: 
        content: 
          application/json: 
            examples: 
              indicesPutDataLifecycleRequestExample1: 
                $ref: "../../specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample1.yaml"
              indicesPutLifecycleRequestExample2:
                $ref: "../../specification/indices/put_data_lifecycle/IndicesPutDataLifecycleRequestExample2.yaml"
      responses:
        200:
          content:
            application/json:
              examples:
                indicesPutDataLifecycleResponseExample1:
                  $ref: "../../specification/indices/put_data_lifecycle/IndicesPutDataLifecycleResponseExample1.yaml"
  - target: "$.paths['/{index}/_lifecycle/explain']['get']"
    description: "Add example for explain data stream lifecycle response"
    update: 
      responses:
        200:
          content:
            application/json:
              examples:
                indicesExplainDataLifecycleResponseExample:
                  $ref: "../../specification/indices/explain_data_lifecycle/IndicesExplainDataLifecycleResponseExample1.yaml"