[9.4] [Docs][Visualizations API] Add schema descriptions to all 12 chart types (Viz PR B) (#263571)#265997
Merged
Conversation
…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> (cherry picked from commit 187a8e0)
2 tasks
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
Comment on lines
60
to
68
| palette: schema.maybe( | ||
| schema.string({ | ||
| meta: { description: 'Palette' }, | ||
| meta: { | ||
| description: | ||
| "Color palette name. Accepted values: 'default', 'elastic_line_optimized', 'severity', 'eui_amsterdam', 'kibana_v7_legacy', 'elastic_brand_2023'. Defaults to `default`.", | ||
| }, | ||
| defaultValue: DEFAULT_SECONDARY_COMPARE_TO_PALETTE, | ||
| }) | ||
| ), |
Contributor
There was a problem hiding this comment.
🟢 Low charts/metric.ts:60
The palette description in compareToSchemaShared claims the default is 'default', but defaultValue: DEFAULT_SECONDARY_COMPARE_TO_PALETTE evaluates to 'compare_to'. The description also omits 'compare_to' from the accepted values list. Update the description to match the actual default and include all valid palette names.
Suggested change
| palette: schema.maybe( | |
| schema.string({ | |
| meta: { description: 'Palette' }, | |
| meta: { | |
| description: | |
| "Color palette name. Accepted values: 'default', 'elastic_line_optimized', 'severity', 'eui_amsterdam', 'kibana_v7_legacy', 'elastic_brand_2023'. Defaults to `default`.", | |
| }, | |
| defaultValue: DEFAULT_SECONDARY_COMPARE_TO_PALETTE, | |
| }) | |
| ), | |
| schema.string({ | |
| meta: { | |
| description: | |
| "Color palette name. Accepted values: 'default', 'elastic_line_optimized', 'severity', 'eui_amsterdam', 'kibana_v7_legacy', 'elastic_brand_2023', 'compare_to'. Defaults to `compare_to`.", | |
| }, | |
| defaultValue: DEFAULT_SECONDARY_COMPARE_TO_PALETTE, | |
| }) |
🤖 Copy this AI Prompt to have your agent fix this:
In file src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/metric.ts around lines 60-68:
The `palette` description in `compareToSchemaShared` claims the default is `'default'`, but `defaultValue: DEFAULT_SECONDARY_COMPARE_TO_PALETTE` evaluates to `'compare_to'`. The description also omits `'compare_to'` from the accepted values list. Update the description to match the actual default and include all valid palette names.
Evidence trail:
src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/schema/charts/metric.ts lines 60-66 (description says "Defaults to `default`." and lists accepted values without 'compare_to'); src/platform/packages/shared/kbn-lens-embeddable-utils/config_builder/transforms/charts/metric/defaults.ts line 27 (`DEFAULT_SECONDARY_COMPARE_TO_PALETTE = 'compare_to' as const`)
Contributor
Author
💚 Build Succeeded
Metrics [docs]Async chunks
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport
This will backport the following commits from
mainto9.4:Questions ?
Please refer to the Backport tool documentation