Elastic Schemas

Schema definitions for all Elastic APIs, including Elasticsearch, Kibana, and Cloud. Available in multiple forms:

• Zod schemas
• plain JSON schemas
• a tool registry optimized for LLM-based agents

Also includes basic utilities for building HTTP API requests from inputs that match one of the provided schemas.

Installation

Install from npm:

npm install @elastic/schemas

Optional dependencies

Zod is an optional dependency. If you only need JSON schemas or the tool registry, you don't need to install Zod. If you want to use Zod schemas, install it explicitly:

npm install zod

Usage

JSON schemas

Static JSON Schema files are available for each API's request and response. Namespaced APIs are named {namespace}.{name}.request.json; top-level (global) APIs are named {name}.request.json.

import searchRequest from '@elastic/schemas/es/json/search.request.json' with { type: 'json' }
import searchResponse from '@elastic/schemas/es/json/search.response.json' with { type: 'json' }

import findRulesRequest from '@elastic/schemas/kibana/json/find_rules.request.json' with { type: 'json' }

import createApiKeyRequest from '@elastic/schemas/cloud/json/create_api_key.request.json' with { type: 'json' }

The schemas can be used directly with any JSON Schema validator, e.g. Ajv:

import Ajv from 'ajv'
import searchRequest from '@elastic/schemas/es/json/search.request.json' with { type: 'json' }

const ajv = new Ajv()
const validate = ajv.compile(searchRequest)

const valid = validate({ index: 'my-index', query: { match_all: {} } })
if (!valid) console.error(validate.errors)

Zod schemas

If you have Zod installed, import individual schemas by their module path and use them like any Zod schema:

import { SearchRequest } from '@elastic/schemas/es/schemas/search.js'

const result = SearchRequest.safeParse({
  index: 'my-index',
  query: { match: { title: 'elasticsearch' } },
  size: 10,
})

if (!result.success) {
  console.error(result.error.issues)
}

Tool registry

Load a tool definition by API ID and build a ready-to-send HTTP request:

import { esRegistry } from '@elastic/schemas/es/tools/index.js'

const api = await esRegistry.loadApi('search')

const request = api.buildRequest({
  index: 'my-index',
  query: { match: { title: 'elasticsearch' } },
  size: 10,
})
// { method: 'GET', path: '/my-index/_search', body: { query: ..., size: 10 } }

Each loaded definition carries two classification flags. destructive marks operations that delete or mutate existing data. readOnly marks operations that only read: every GET and HEAD call except a few with side effects, plus search-style POST calls such as count or sql.query. A read-only operation is never destructive. The same flags appear on the JSON Schema request documents as x-destructive and x-read-only.

Browse available API IDs via esRegistry.manifest (an array of { id, name, namespace, description, destructive, readOnly } entries).

Tool manifests

Each product exposes a manifest: a lightweight array of ApiRegistryMeta objects describing every available API ({ id, name, namespace, description, namespaceFile, destructive, readOnly }). The destructive and readOnly flags match the loaded definition's, so you can filter APIs by classification without loading any definitions. You can import a manifest directly without loading any schema code:

import { kibanaManifest } from '@elastic/schemas/kibana/tools/manifest.js'
import { esManifest } from '@elastic/schemas/es/tools/manifest.js'
import { cloudManifest } from '@elastic/schemas/cloud/tools/manifest.js'
import { serverlessManifest } from '@elastic/schemas/serverless/tools/manifest.js'

The ApiRegistryMeta type is exported from the main entry point:

import type { ApiRegistryMeta } from '@elastic/schemas'

Available exports

:warning: Importing all the schemas as a single object is going to consume a lot of memory, so we encourage you to use the exact path to the schema you need:

import { SearchRequest } from '@elastic/schemas/es/schemas/search.js'

However, if you do need a full export as one object, the following exports are provided:

Version support

The schemas in this package reflect the API specifications for the latest Elasticsearch Serverless release of Elasticsearch and Kibana only, as well as the latest stable release of the Elastic Cloud control plane API. Support for other versions of the Elastic stack is coming!