Skip to content

[Docs][Visualizations API] Add endpoint and field descriptions#263151

Merged
florent-leborgne merged 8 commits into
mainfrom
lens-api-docs-4
Apr 20, 2026
Merged

[Docs][Visualizations API] Add endpoint and field descriptions#263151
florent-leborgne merged 8 commits into
mainfrom
lens-api-docs-4

Conversation

@florent-leborgne
Copy link
Copy Markdown
Member

@florent-leborgne florent-leborgne commented Apr 14, 2026 •
edited by kibanamachine
Loading

Summary

Part of the Lens Visualizations API documentation series.

Series:

What changed

Route files — all 5 endpoints

Added description strings and since: '9.4.0' to all five routes.

schema/search.ts, schema/create.ts, schema/common.ts

  • query search param: description added inline
  • id path param on delete/get/update: improved description
  • total response field: description added inline

schema/delete.ts, schema/get.ts, schema/update.ts

Updated id description to reference where the ID comes from.

Shared package: @kbn/as-code-shared-schemas

Added meta.description to all 7 fields of asCodeMetaSchema (created_at, created_by, managed, owner, updated_at, updated_by, version).

Note: descriptions added to @kbn/content-management-utils (savedObjectSchema.id, searchOptionsSchemas.*, createOptionsSchemas.overwrite) were reverted per feedback from ThomThomson — content management schemas are not part of the public as-code API surface. Descriptions for fields, search_fields, overwrite, and id will be handled via overlay fallback.

Open items

  • Two CodeQL findings on kbn-content-management-utils/src/schema.ts (unbounded arrays) — pre-existing, not introduced by this PR
  • davismcphee's architectural question answered: content-management-utils changes reverted

🤖 Generated with Claude Code

florent-leborgne and others added 3 commits April 14, 2026 18:56
@florent-leborgne @claude
[Docs][Visualizations API] Add endpoint descriptions and field descri…
2792c48 
…ptions

- Add operation descriptions and since: '9.4.0' to all 5 route files
  (create, search, get, update, delete)
- Add field descriptions to search query params (fields, search_fields,
  query, page, per_page) and response meta (page, per_page, total)
- Add id description to lensResponseItemSchema
- Add overwrite description to lensCreateRequestQuerySchema (inline)
- Add id descriptions to delete/get/update params schemas
- Add field descriptions to asCodeMetaSchema in @kbn/as-code-shared-schemas
  (created_at, created_by, managed, owner, updated_at, updated_by, version)
  so all API consumers benefit

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne @claude
[Docs][Visualizations API] Move field descriptions to shared schemas
33221f1 
Instead of inlining schemas to add descriptions, add descriptions directly
to the shared schemas in @kbn/content-management-utils so all API consumers
benefit (Lens, Dashboards, SavedSearch, DataViews, Maps, etc.):

- searchOptionsSchemas.fields, .searchFields, .page, .perPage
- createOptionsSchemas.overwrite

Restore the original import structure in schema/search.ts and
schema/create.ts — both files now reference the shared schemas again
with no structural changes.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne @claude
[Docs][Visualizations API] Add id description to savedObjectSchema, r…
6aec147 
…estore import

Add generic 'Unique identifier.' description to savedObjectSchema.id in
@kbn/content-management-utils so all content management consumers benefit.
Revert schema/common.ts to reference savedObjectProps.id again — no net
import changes from main.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne florent-leborgne marked this pull request as ready for review April 14, 2026 18:06
@florent-leborgne florent-leborgne requested review from a team as code owners April 14, 2026 18:06
@florent-leborgne florent-leborgne added Team:Docs backport:skip This PR does not require backporting docs APIDocs backport:version Backport to applied version labels v9.4.0 labels Apr 14, 2026
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Apr 14, 2026

Pinging @elastic/experience-docs (Team:Docs)

@florent-leborgne florent-leborgne added release_note:skip Skip the PR/issue when compiling release notes and removed backport:skip This PR does not require backporting labels Apr 14, 2026
github-advanced-security[bot]
github-advanced-security AI found potential problems Apr 14, 2026
View reviewed changes
Comment thread src/platform/packages/shared/kbn-content-management-utils/src/schema.ts Fixed
Comment thread src/platform/packages/shared/kbn-content-management-utils/src/schema.ts Fixed
nreese
nreese approved these changes Apr 14, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@nreese nreese left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kibana-presentation changes LGTM
code review only

davismcphee
davismcphee approved these changes Apr 15, 2026
View reviewed changes
Comment thread src/platform/packages/shared/kbn-content-management-utils/src/schema.ts
This was referenced Apr 15, 2026
Merged
Closed
Closed
florent-leborgne and others added 2 commits April 16, 2026 20:50
@florent-leborgne @claude
[Docs][Visualizations API] Revert content-management-utils descriptio…
0979783 
…n changes

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne
Merge branch 'main' into lens-api-docs-4
9ab6802
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Apr 20, 2026

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

  • [job] [logs] FTR Configs #107 / cases security and spaces enabled: trial Kibana index: Alerting & Cases "before all" hook for "migrates the cases SO from the .kibana index to the .kibana_alerting_cases correctly"
  • [job] [logs] FTR Configs #1 / Entity Analytics - Risk Score Maintainer @ess @serverless @serverlessQA Risk Score Maintainer Task Lifecycle with maintainer test logs data @skipInServerlessMKI resumes producing additional scores after stop and restart when triggered
  • [job] [logs] affected Scout: [ platform / streams_app-serverless-observability_complete ] plugin / local-serverless-observability_complete - Stream data mapping - schema editor - should allow unmapping a field
  • [job] [logs] affected Scout: [ platform / streams_app-stateful-classic ] plugin / local-stateful-classic - Stream data routing - creating routing rules - should cancel creating new routing rule

Metrics [docs]

✅ unchanged

History

@florent-leborgne florent-leborgne merged commit c2bbbc4 into main Apr 20, 2026
19 checks passed
@florent-leborgne florent-leborgne deleted the lens-api-docs-4 branch April 20, 2026 13:39
@kibanamachine
Copy link
Copy Markdown
Contributor

kibanamachine commented Apr 20, 2026

Starting backport for target branches: 9.4

https://github.com/elastic/kibana/actions/runs/24669765217

kibanamachine added a commit to kibanamachine/kibana that referenced this pull request Apr 20, 2026
@florent-leborgne @claude @kibanamachine
[Docs][Visualizations API] Add endpoint and field descriptions (elast…
d70d9b2 
…ic#263151)

## Summary

Part of the Lens Visualizations API documentation series.

**Series:**
- PR 1/4: Introduction and get-started overlay — merged (elastic#262595)
- **PR 2/4 (this PR):** Endpoint descriptions and field descriptions
- PR 3/4: Request code samples and response examples (elastic#262874)
- Viz PR B: Chart type schema descriptions (elastic#263571)

## What changed

### Route files — all 5 endpoints
Added `description` strings and `since: '9.4.0'` to all five routes.

### `schema/search.ts`, `schema/create.ts`, `schema/common.ts`
- `query` search param: description added inline
- `id` path param on delete/get/update: improved description
- `total` response field: description added inline

### `schema/delete.ts`, `schema/get.ts`, `schema/update.ts`
Updated `id` description to reference where the ID comes from.

### Shared package: `@kbn/as-code-shared-schemas`
Added `meta.description` to all 7 fields of `asCodeMetaSchema`
(`created_at`, `created_by`, `managed`, `owner`, `updated_at`,
`updated_by`, `version`).

> **Note:** descriptions added to `@kbn/content-management-utils`
(`savedObjectSchema.id`, `searchOptionsSchemas.*`,
`createOptionsSchemas.overwrite`) were **reverted** per feedback from
ThomThomson — content management schemas are not part of the public
as-code API surface. Descriptions for `fields`, `search_fields`,
`overwrite`, and `id` will be handled via overlay fallback.

## Open items
- Two CodeQL findings on `kbn-content-management-utils/src/schema.ts`
(unbounded arrays) — pre-existing, not introduced by this PR
- davismcphee's architectural question answered:
content-management-utils changes reverted

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
(cherry picked from commit c2bbbc4)
@kibanamachine kibanamachine mentioned this pull request Apr 20, 2026
Merged
@kibanamachine
Copy link
Copy Markdown
Contributor

kibanamachine commented Apr 20, 2026

💚 All backports created successfully

Status Branch Result
✅ 9.4

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

kibanamachine added a commit that referenced this pull request Apr 20, 2026
@kibanamachine @florent-leborgne @claude
[9.4] [Docs][Visualizations API] Add endpoint and field descriptions (#…
620dbd2 
…263151) (#264423)

# Backport

This will backport the following commits from `main` to `9.4`:
- [[Docs][Visualizations API] Add endpoint and field descriptions
(#263151)](#263151)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Florent
LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-20T13:39:35Z","message":"[Docs][Visualizations
API] Add endpoint and field descriptions (#263151)\n\n## Summary\n\nPart
of the Lens Visualizations API documentation series.\n\n**Series:**\n-
PR 1/4: Introduction and get-started overlay — merged (#262595)\n- **PR
2/4 (this PR):** Endpoint descriptions and field descriptions\n- PR 3/4:
Request code samples and response examples (#262874)\n- Viz PR B: Chart
type schema descriptions (#263571)\n\n## What changed\n\n### Route files
— all 5 endpoints\nAdded `description` strings and `since: '9.4.0'` to
all five routes.\n\n### `schema/search.ts`, `schema/create.ts`,
`schema/common.ts`\n- `query` search param: description added inline\n-
`id` path param on delete/get/update: improved description\n- `total`
response field: description added inline\n\n### `schema/delete.ts`,
`schema/get.ts`, `schema/update.ts`\nUpdated `id` description to
reference where the ID comes from.\n\n### Shared package:
`@kbn/as-code-shared-schemas`\nAdded `meta.description` to all 7 fields
of `asCodeMetaSchema`\n(`created_at`, `created_by`, `managed`, `owner`,
`updated_at`,\n`updated_by`, `version`).\n\n> **Note:** descriptions
added to `@kbn/content-management-utils`\n(`savedObjectSchema.id`,
`searchOptionsSchemas.*`,\n`createOptionsSchemas.overwrite`) were
**reverted** per feedback from\nThomThomson — content management schemas
are not part of the public\nas-code API surface. Descriptions for
`fields`, `search_fields`,\n`overwrite`, and `id` will be handled via
overlay fallback.\n\n## Open items\n- Two CodeQL findings on
`kbn-content-management-utils/src/schema.ts`\n(unbounded arrays) —
pre-existing, not introduced by this PR\n- davismcphee's architectural
question answered:\ncontent-management-utils changes reverted\n\n🤖
Generated with [Claude
Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by:
Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"c2bbbc461b994391921301fb2960e7a0b5df929b","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Visualizations
API] Add endpoint and field
descriptions","number":263151,"url":"https://github.com/elastic/kibana/pull/263151","mergeCommit":{"message":"[Docs][Visualizations
API] Add endpoint and field descriptions (#263151)\n\n## Summary\n\nPart
of the Lens Visualizations API documentation series.\n\n**Series:**\n-
PR 1/4: Introduction and get-started overlay — merged (#262595)\n- **PR
2/4 (this PR):** Endpoint descriptions and field descriptions\n- PR 3/4:
Request code samples and response examples (#262874)\n- Viz PR B: Chart
type schema descriptions (#263571)\n\n## What changed\n\n### Route files
— all 5 endpoints\nAdded `description` strings and `since: '9.4.0'` to
all five routes.\n\n### `schema/search.ts`, `schema/create.ts`,
`schema/common.ts`\n- `query` search param: description added inline\n-
`id` path param on delete/get/update: improved description\n- `total`
response field: description added inline\n\n### `schema/delete.ts`,
`schema/get.ts`, `schema/update.ts`\nUpdated `id` description to
reference where the ID comes from.\n\n### Shared package:
`@kbn/as-code-shared-schemas`\nAdded `meta.description` to all 7 fields
of `asCodeMetaSchema`\n(`created_at`, `created_by`, `managed`, `owner`,
`updated_at`,\n`updated_by`, `version`).\n\n> **Note:** descriptions
added to `@kbn/content-management-utils`\n(`savedObjectSchema.id`,
`searchOptionsSchemas.*`,\n`createOptionsSchemas.overwrite`) were
**reverted** per feedback from\nThomThomson — content management schemas
are not part of the public\nas-code API surface. Descriptions for
`fields`, `search_fields`,\n`overwrite`, and `id` will be handled via
overlay fallback.\n\n## Open items\n- Two CodeQL findings on
`kbn-content-management-utils/src/schema.ts`\n(unbounded arrays) —
pre-existing, not introduced by this PR\n- davismcphee's architectural
question answered:\ncontent-management-utils changes reverted\n\n🤖
Generated with [Claude
Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by:
Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"c2bbbc461b994391921301fb2960e7a0b5df929b"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/263151","number":263151,"mergeCommit":{"message":"[Docs][Visualizations
API] Add endpoint and field descriptions (#263151)\n\n## Summary\n\nPart
of the Lens Visualizations API documentation series.\n\n**Series:**\n-
PR 1/4: Introduction and get-started overlay — merged (#262595)\n- **PR
2/4 (this PR):** Endpoint descriptions and field descriptions\n- PR 3/4:
Request code samples and response examples (#262874)\n- Viz PR B: Chart
type schema descriptions (#263571)\n\n## What changed\n\n### Route files
— all 5 endpoints\nAdded `description` strings and `since: '9.4.0'` to
all five routes.\n\n### `schema/search.ts`, `schema/create.ts`,
`schema/common.ts`\n- `query` search param: description added inline\n-
`id` path param on delete/get/update: improved description\n- `total`
response field: description added inline\n\n### `schema/delete.ts`,
`schema/get.ts`, `schema/update.ts`\nUpdated `id` description to
reference where the ID comes from.\n\n### Shared package:
`@kbn/as-code-shared-schemas`\nAdded `meta.description` to all 7 fields
of `asCodeMetaSchema`\n(`created_at`, `created_by`, `managed`, `owner`,
`updated_at`,\n`updated_by`, `version`).\n\n> **Note:** descriptions
added to `@kbn/content-management-utils`\n(`savedObjectSchema.id`,
`searchOptionsSchemas.*`,\n`createOptionsSchemas.overwrite`) were
**reverted** per feedback from\nThomThomson — content management schemas
are not part of the public\nas-code API surface. Descriptions for
`fields`, `search_fields`,\n`overwrite`, and `id` will be handled via
overlay fallback.\n\n## Open items\n- Two CodeQL findings on
`kbn-content-management-utils/src/schema.ts`\n(unbounded arrays) —
pre-existing, not introduced by this PR\n- davismcphee's architectural
question answered:\ncontent-management-utils changes reverted\n\n🤖
Generated with [Claude
Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by:
Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"c2bbbc461b994391921301fb2960e7a0b5df929b"}}]}]
BACKPORT-->

Co-authored-by: Florent LB <florent.leborgne@elastic.co>
Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
florent-leborgne added a commit that referenced this pull request Apr 28, 2026
@florent-leborgne @claude
@kibanamachine @markov00
[Docs][Visualizations API] Add schema descriptions to all 12 chart ty…
187a8e0 
…pes (Viz PR B) (#263571)

## Summary

Part of the Lens Visualizations API documentation series (Viz PR B).
Adds descriptions to all 12 chart type schemas and all supporting
schemas.

**Series:**
- PR 1/4: Introduction overlay — merged (#262595)
- PR 2/4: Endpoint + field descriptions (#263151)
- PR 3/4: Code samples + response examples (#262874)
- **Viz PR B (this PR):** Schema descriptions for all 12 chart types +
supporting schemas

## Approach

Descriptions only — no schema types, validation constraints, or field
names changed. Rebased onto main to pick up #262927 (styling alignment
restructuring).

## What changed

### Operation schemas
- `metric_ops.ts`: object-level descriptions on
`metricOperationDefinitionSchema`,
`fieldMetricOrFormulaOperationDefinitionSchema`
- `bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema` and
all bucket operation fields; `When \`true\`,` pattern applied throughout
- `shared.ts`: fixed tautological `collapseBySchema` description; fixed
`ignore_global_filters` and `sampling` descriptions; fixed
`axisTitleSchemaProps`

### Chart schemas — all 12 types
Object-level descriptions on DSL variant, ES|QL variant, and union
schema for every chart type. "DSL data source" consistently replaced
with "data view". Additional field-level descriptions on chart-specific
fields (shape, alignment, icon, palette, etc.).

### Supporting schemas
- `color.ts`: descriptions on all color variant schemas; full palette
name list on all palette fields with correct defaults per context
- `format.ts`: descriptions on all format variant schemas
- `filter.ts`: descriptions on `filterSchema` and
`filterWithLabelSchema`
- `index.ts`: description on `lensApiStateSchema` top-level union
- `xy.ts`: `aggregate_first` description fixed

### Style quality pass
- All descriptions standardised to noun phrases (no verb-first
descriptions)
- `A/An` added to concrete countable noun descriptions
- Dropped valid enum values restored (alignment, slice label position,
donut hole size)
- Redundant numeric min/max removed from description text (auto-rendered
by OAS)
- `may` → `can` throughout

### Reverted
Object-level descriptions added to `@kbn/as-code-data-views-schema`
(`dataViewReferenceSchema`, `dataViewSpecSchema`, `runtimeFieldSchema`,
etc.) were **reverted** — object-level `meta.description` on schema
objects in shared packages does not surface in the OAS output. Will use
overlay fallback.

## Test plan
- [x] Rebased onto main; conflicts from #262927 resolved
- [x] Descriptions verified in combined OAS preview on Bump

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: florent-leborgne <10208282+florent-leborgne@users.noreply.github.com>
Co-authored-by: Marco Vettorello <vettorello.marco@gmail.com>
kibanamachine added a commit that referenced this pull request Apr 28, 2026
@kibanamachine @florent-leborgne
@claude @markov00
[9.4] [Docs][Visualizations API] Add schema descriptions to all 12 ch…
3520122 
…art types (Viz PR B) (#263571) (#265997)

# Backport

This will backport the following commits from `main` to `9.4`:
- [[Docs][Visualizations API] Add schema descriptions to all 12 chart
types (Viz PR B)
(#263571)](#263571)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Florent
LB","email":"florent.leborgne@elastic.co"},"sourceCommit":{"committedDate":"2026-04-28T09:59:20Z","message":"[Docs][Visualizations
API] Add schema descriptions to all 12 chart types (Viz PR B)
(#263571)\n\n## Summary\n\nPart of the Lens Visualizations API
documentation series (Viz PR B).\nAdds descriptions to all 12 chart type
schemas and all supporting\nschemas.\n\n**Series:**\n- PR 1/4:
Introduction overlay — merged (#262595)\n- PR 2/4: Endpoint + field
descriptions (#263151)\n- PR 3/4: Code samples + response examples
(#262874)\n- **Viz PR B (this PR):** Schema descriptions for all 12
chart types +\nsupporting schemas\n\n## Approach\n\nDescriptions only —
no schema types, validation constraints, or field\nnames changed.
Rebased onto main to pick up #262927 (styling
alignment\nrestructuring).\n\n## What changed\n\n### Operation
schemas\n- `metric_ops.ts`: object-level descriptions
on\n`metricOperationDefinitionSchema`,\n`fieldMetricOrFormulaOperationDefinitionSchema`\n-
`bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema`
and\nall bucket operation fields; `When \\`true\\`,` pattern applied
throughout\n- `shared.ts`: fixed tautological `collapseBySchema`
description; fixed\n`ignore_global_filters` and `sampling` descriptions;
fixed\n`axisTitleSchemaProps`\n\n### Chart schemas — all 12
types\nObject-level descriptions on DSL variant, ES|QL variant, and
union\nschema for every chart type. \"DSL data source\" consistently
replaced\nwith \"data view\". Additional field-level descriptions on
chart-specific\nfields (shape, alignment, icon, palette, etc.).\n\n###
Supporting schemas\n- `color.ts`: descriptions on all color variant
schemas; full palette\nname list on all palette fields with correct
defaults per context\n- `format.ts`: descriptions on all format variant
schemas\n- `filter.ts`: descriptions on `filterSchema`
and\n`filterWithLabelSchema`\n- `index.ts`: description on
`lensApiStateSchema` top-level union\n- `xy.ts`: `aggregate_first`
description fixed\n\n### Style quality pass\n- All descriptions
standardised to noun phrases (no verb-first\ndescriptions)\n- `A/An`
added to concrete countable noun descriptions\n- Dropped valid enum
values restored (alignment, slice label position,\ndonut hole size)\n-
Redundant numeric min/max removed from description text
(auto-rendered\nby OAS)\n- `may` → `can` throughout\n\n###
Reverted\nObject-level descriptions added to
`@kbn/as-code-data-views-schema`\n(`dataViewReferenceSchema`,
`dataViewSpecSchema`, `runtimeFieldSchema`,\netc.) were **reverted** —
object-level `meta.description` on schema\nobjects in shared packages
does not surface in the OAS output. Will use\noverlay fallback.\n\n##
Test plan\n- [x] Rebased onto main; conflicts from #262927 resolved\n-
[x] Descriptions verified in combined OAS preview on Bump\n\n🤖 Generated
with [Claude
Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by:
Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\nCo-authored-by:
copilot-swe-agent[bot]
<198982749+Copilot@users.noreply.github.com>\nCo-authored-by:
florent-leborgne
<10208282+florent-leborgne@users.noreply.github.com>\nCo-authored-by:
Marco Vettorello
<vettorello.marco@gmail.com>","sha":"187a8e0c74b9cd78b0b963e3abf92211bc0a7939","branchLabelMapping":{"^v9.5.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Docs","release_note:skip","docs","APIDocs","backport:version","v9.4.0","v9.5.0"],"title":"[Docs][Visualizations
API] Add schema descriptions to all 12 chart types (Viz PR
B)","number":263571,"url":"https://github.com/elastic/kibana/pull/263571","mergeCommit":{"message":"[Docs][Visualizations
API] Add schema descriptions to all 12 chart types (Viz PR B)
(#263571)\n\n## Summary\n\nPart of the Lens Visualizations API
documentation series (Viz PR B).\nAdds descriptions to all 12 chart type
schemas and all supporting\nschemas.\n\n**Series:**\n- PR 1/4:
Introduction overlay — merged (#262595)\n- PR 2/4: Endpoint + field
descriptions (#263151)\n- PR 3/4: Code samples + response examples
(#262874)\n- **Viz PR B (this PR):** Schema descriptions for all 12
chart types +\nsupporting schemas\n\n## Approach\n\nDescriptions only —
no schema types, validation constraints, or field\nnames changed.
Rebased onto main to pick up #262927 (styling
alignment\nrestructuring).\n\n## What changed\n\n### Operation
schemas\n- `metric_ops.ts`: object-level descriptions
on\n`metricOperationDefinitionSchema`,\n`fieldMetricOrFormulaOperationDefinitionSchema`\n-
`bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema`
and\nall bucket operation fields; `When \\`true\\`,` pattern applied
throughout\n- `shared.ts`: fixed tautological `collapseBySchema`
description; fixed\n`ignore_global_filters` and `sampling` descriptions;
fixed\n`axisTitleSchemaProps`\n\n### Chart schemas — all 12
types\nObject-level descriptions on DSL variant, ES|QL variant, and
union\nschema for every chart type. \"DSL data source\" consistently
replaced\nwith \"data view\". Additional field-level descriptions on
chart-specific\nfields (shape, alignment, icon, palette, etc.).\n\n###
Supporting schemas\n- `color.ts`: descriptions on all color variant
schemas; full palette\nname list on all palette fields with correct
defaults per context\n- `format.ts`: descriptions on all format variant
schemas\n- `filter.ts`: descriptions on `filterSchema`
and\n`filterWithLabelSchema`\n- `index.ts`: description on
`lensApiStateSchema` top-level union\n- `xy.ts`: `aggregate_first`
description fixed\n\n### Style quality pass\n- All descriptions
standardised to noun phrases (no verb-first\ndescriptions)\n- `A/An`
added to concrete countable noun descriptions\n- Dropped valid enum
values restored (alignment, slice label position,\ndonut hole size)\n-
Redundant numeric min/max removed from description text
(auto-rendered\nby OAS)\n- `may` → `can` throughout\n\n###
Reverted\nObject-level descriptions added to
`@kbn/as-code-data-views-schema`\n(`dataViewReferenceSchema`,
`dataViewSpecSchema`, `runtimeFieldSchema`,\netc.) were **reverted** —
object-level `meta.description` on schema\nobjects in shared packages
does not surface in the OAS output. Will use\noverlay fallback.\n\n##
Test plan\n- [x] Rebased onto main; conflicts from #262927 resolved\n-
[x] Descriptions verified in combined OAS preview on Bump\n\n🤖 Generated
with [Claude
Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by:
Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\nCo-authored-by:
copilot-swe-agent[bot]
<198982749+Copilot@users.noreply.github.com>\nCo-authored-by:
florent-leborgne
<10208282+florent-leborgne@users.noreply.github.com>\nCo-authored-by:
Marco Vettorello
<vettorello.marco@gmail.com>","sha":"187a8e0c74b9cd78b0b963e3abf92211bc0a7939"}},"sourceBranch":"main","suggestedTargetBranches":["9.4"],"targetPullRequestStates":[{"branch":"9.4","label":"v9.4.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.5.0","branchLabelMappingKey":"^v9.5.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/263571","number":263571,"mergeCommit":{"message":"[Docs][Visualizations
API] Add schema descriptions to all 12 chart types (Viz PR B)
(#263571)\n\n## Summary\n\nPart of the Lens Visualizations API
documentation series (Viz PR B).\nAdds descriptions to all 12 chart type
schemas and all supporting\nschemas.\n\n**Series:**\n- PR 1/4:
Introduction overlay — merged (#262595)\n- PR 2/4: Endpoint + field
descriptions (#263151)\n- PR 3/4: Code samples + response examples
(#262874)\n- **Viz PR B (this PR):** Schema descriptions for all 12
chart types +\nsupporting schemas\n\n## Approach\n\nDescriptions only —
no schema types, validation constraints, or field\nnames changed.
Rebased onto main to pick up #262927 (styling
alignment\nrestructuring).\n\n## What changed\n\n### Operation
schemas\n- `metric_ops.ts`: object-level descriptions
on\n`metricOperationDefinitionSchema`,\n`fieldMetricOrFormulaOperationDefinitionSchema`\n-
`bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema`
and\nall bucket operation fields; `When \\`true\\`,` pattern applied
throughout\n- `shared.ts`: fixed tautological `collapseBySchema`
description; fixed\n`ignore_global_filters` and `sampling` descriptions;
fixed\n`axisTitleSchemaProps`\n\n### Chart schemas — all 12
types\nObject-level descriptions on DSL variant, ES|QL variant, and
union\nschema for every chart type. \"DSL data source\" consistently
replaced\nwith \"data view\". Additional field-level descriptions on
chart-specific\nfields (shape, alignment, icon, palette, etc.).\n\n###
Supporting schemas\n- `color.ts`: descriptions on all color variant
schemas; full palette\nname list on all palette fields with correct
defaults per context\n- `format.ts`: descriptions on all format variant
schemas\n- `filter.ts`: descriptions on `filterSchema`
and\n`filterWithLabelSchema`\n- `index.ts`: description on
`lensApiStateSchema` top-level union\n- `xy.ts`: `aggregate_first`
description fixed\n\n### Style quality pass\n- All descriptions
standardised to noun phrases (no verb-first\ndescriptions)\n- `A/An`
added to concrete countable noun descriptions\n- Dropped valid enum
values restored (alignment, slice label position,\ndonut hole size)\n-
Redundant numeric min/max removed from description text
(auto-rendered\nby OAS)\n- `may` → `can` throughout\n\n###
Reverted\nObject-level descriptions added to
`@kbn/as-code-data-views-schema`\n(`dataViewReferenceSchema`,
`dataViewSpecSchema`, `runtimeFieldSchema`,\netc.) were **reverted** —
object-level `meta.description` on schema\nobjects in shared packages
does not surface in the OAS output. Will use\noverlay fallback.\n\n##
Test plan\n- [x] Rebased onto main; conflicts from #262927 resolved\n-
[x] Descriptions verified in combined OAS preview on Bump\n\n🤖 Generated
with [Claude
Code](https://claude.com/claude-code)\n\n---------\n\nCo-authored-by:
Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>\nCo-authored-by:
copilot-swe-agent[bot]
<198982749+Copilot@users.noreply.github.com>\nCo-authored-by:
florent-leborgne
<10208282+florent-leborgne@users.noreply.github.com>\nCo-authored-by:
Marco Vettorello
<vettorello.marco@gmail.com>","sha":"187a8e0c74b9cd78b0b963e3abf92211bc0a7939"}}]}]
BACKPORT-->

Co-authored-by: Florent LB <florent.leborgne@elastic.co>
Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: florent-leborgne <10208282+florent-leborgne@users.noreply.github.com>
Co-authored-by: Marco Vettorello <vettorello.marco@gmail.com>
smith pushed a commit to smith/kibana that referenced this pull request Apr 28, 2026
@florent-leborgne @claude
@kibanamachine @markov00 @smith
[Docs][Visualizations API] Add schema descriptions to all 12 chart ty…
79cc762 
…pes (Viz PR B) (elastic#263571)

## Summary

Part of the Lens Visualizations API documentation series (Viz PR B).
Adds descriptions to all 12 chart type schemas and all supporting
schemas.

**Series:**
- PR 1/4: Introduction overlay — merged (elastic#262595)
- PR 2/4: Endpoint + field descriptions (elastic#263151)
- PR 3/4: Code samples + response examples (elastic#262874)
- **Viz PR B (this PR):** Schema descriptions for all 12 chart types +
supporting schemas

## Approach

Descriptions only — no schema types, validation constraints, or field
names changed. Rebased onto main to pick up elastic#262927 (styling alignment
restructuring).

## What changed

### Operation schemas
- `metric_ops.ts`: object-level descriptions on
`metricOperationDefinitionSchema`,
`fieldMetricOrFormulaOperationDefinitionSchema`
- `bucket_ops.ts`: descriptions on `bucketOperationDefinitionSchema` and
all bucket operation fields; `When \`true\`,` pattern applied throughout
- `shared.ts`: fixed tautological `collapseBySchema` description; fixed
`ignore_global_filters` and `sampling` descriptions; fixed
`axisTitleSchemaProps`

### Chart schemas — all 12 types
Object-level descriptions on DSL variant, ES|QL variant, and union
schema for every chart type. "DSL data source" consistently replaced
with "data view". Additional field-level descriptions on chart-specific
fields (shape, alignment, icon, palette, etc.).

### Supporting schemas
- `color.ts`: descriptions on all color variant schemas; full palette
name list on all palette fields with correct defaults per context
- `format.ts`: descriptions on all format variant schemas
- `filter.ts`: descriptions on `filterSchema` and
`filterWithLabelSchema`
- `index.ts`: description on `lensApiStateSchema` top-level union
- `xy.ts`: `aggregate_first` description fixed

### Style quality pass
- All descriptions standardised to noun phrases (no verb-first
descriptions)
- `A/An` added to concrete countable noun descriptions
- Dropped valid enum values restored (alignment, slice label position,
donut hole size)
- Redundant numeric min/max removed from description text (auto-rendered
by OAS)
- `may` → `can` throughout

### Reverted
Object-level descriptions added to `@kbn/as-code-data-views-schema`
(`dataViewReferenceSchema`, `dataViewSpecSchema`, `runtimeFieldSchema`,
etc.) were **reverted** — object-level `meta.description` on schema
objects in shared packages does not surface in the OAS output. Will use
overlay fallback.

## Test plan
- [x] Rebased onto main; conflicts from elastic#262927 resolved
- [x] Descriptions verified in combined OAS preview on Bump

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: florent-leborgne <10208282+florent-leborgne@users.noreply.github.com>
Co-authored-by: Marco Vettorello <vettorello.marco@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@nreese nreese nreese approved these changes

@markov00 markov00 markov00 approved these changes

@davismcphee davismcphee davismcphee approved these changes

@teresaalvarezsoler teresaalvarezsoler Awaiting requested review from teresaalvarezsoler

+1 more reviewer

@github-advanced-security github-advanced-security[bot] github-advanced-security[bot] left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

APIDocs backport:version Backport to applied version labels docs release_note:skip Skip the PR/issue when compiling release notes Team:Docs v9.4.0 v9.5.0

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

8 participants

@florent-leborgne @elasticmachine @kibanamachine @nreese @markov00 @davismcphee @github-advanced-security @nastasha-solomon