Skip to content

[Docs][Dashboards API] Add field descriptions to timeRangeSchema and refreshIntervalSchema#263281

Merged
florent-leborgne merged 6 commits into
mainfrom
dashboards-api-docs-2b
Apr 17, 2026
Merged

[Docs][Dashboards API] Add field descriptions to timeRangeSchema and refreshIntervalSchema#263281
florent-leborgne merged 6 commits into
mainfrom
dashboards-api-docs-2b

Conversation

@florent-leborgne
Copy link
Copy Markdown
Member

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

Summary

Adds API-agnostic field descriptions to two shared schema files used as $ref components by the Dashboards API (and other APIs including Maps and ML):

  • kbn-es-query-server — timeRangeSchema: descriptions for from, to, and mode fields with date math links; title meta on absolute/relative variants; object-level title and description.
  • kbn-data-service-server — refreshIntervalSchema: fixed inverted pause description; improved value description; object-level title and description.

All descriptions are API-agnostic and follow the shared schema style rules.

Test plan

  • ESLint passes on both files
  • Descriptions render in combined OAS preview on Bump

🤖 Generated with Claude Code

@florent-leborgne @claude
[Docs][Dashboards API] Add field descriptions to timeRangeSchema and …
ad8d022 
…refreshIntervalSchema

API-agnostic descriptions for shared schemas used by the Dashboards API (and others).
Fixes inverted pause description in refreshIntervalSchema.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@florent-leborgne florent-leborgne force-pushed the dashboards-api-docs-2b branch 2 times, most recently from 93bddb9 to 1f88b97 Compare April 15, 2026 17:54
@florent-leborgne @claude
[Docs][Dashboards API] Add title and description to asCodeQuerySchema
06af625 
Adds object-level title 'Query' and description to the shared query schema
so it renders correctly as a named component in Bump.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
This was referenced Apr 15, 2026
Merged
Closed
Closed
@florent-leborgne @claude
[Docs][Dashboards API] Add date math links to timeRangeSchema descrip…
b417891 
…tions

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 16, 2026 13:02
@florent-leborgne florent-leborgne requested review from a team as code owners April 16, 2026 13:02
@florent-leborgne florent-leborgne added Team:Docs release_note:skip Skip the PR/issue when compiling release notes docs APIDocs backport:version Backport to applied version labels v9.4.0 labels Apr 16, 2026
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Apr 16, 2026

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

nreese
nreese approved these changes Apr 16, 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

@florent-leborgne
Merge branch 'main' into dashboards-api-docs-2b
b65f8d3
@florent-leborgne
[Docs][Dashboards API] Fix type error: remove unsupported meta arg fr…
b696683 
…om schema.literal()

schema.literal() only accepts a single value argument; the meta/options
parameter does not exist on its signature, causing the Check Types CI step
to fail.

Made-with: Cursor
@florent-leborgne florent-leborgne mentioned this pull request Apr 16, 2026
Merged
3 tasks
florent-leborgne added a commit that referenced this pull request Apr 16, 2026
@florent-leborgne @claude
[Docs][Dashboards API] Add request and response examples for all 5 en…
f6059b0 
…dpoints (#262865)

## Summary

- Adds cURL and Console code samples (`x-codeSamples`) to all 5
Dashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE
`/{id}`, GET `_find`)
- POST includes two examples: simple dashboard (markdown + 2 metrics +
ES|QL line chart) and a structured dashboard with sections and controls
- Adds inlined response examples for POST (201), GET (200), PUT (200),
and GET `_find` (200)

All examples tested against a live Kibana 9.4.0 instance using the
Kibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid
best practices documented in the tag description (PR #262396).

Part of the Dashboards API documentation series: #262396 (merged) →
descriptions (#263166, #263281, #263282, #263283) → this PR.

## Preview


https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards

## Test plan

- [ ] Generate Bump preview and verify code samples appear in upper
right dropdown for each endpoint
- [ ] Verify response examples appear in the Responses section
- [ ] Confirm all JSON in code samples is fully expanded (no inline
objects)

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

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
@elasticmachine
Copy link
Copy Markdown
Contributor

elasticmachine commented Apr 16, 2026

💚 Build Succeeded

Metrics [docs]

✅ unchanged

History

kibanamachine pushed a commit to kibanamachine/kibana that referenced this pull request Apr 16, 2026
@florent-leborgne @claude
[Docs][Dashboards API] Add request and response examples for all 5 en…
2edb6e6 
…dpoints (elastic#262865)

## Summary

- Adds cURL and Console code samples (`x-codeSamples`) to all 5
Dashboards API endpoints (POST, GET `/{id}`, PUT `/{id}`, DELETE
`/{id}`, GET `_find`)
- POST includes two examples: simple dashboard (markdown + 2 metrics +
ES|QL line chart) and a structured dashboard with sections and controls
- Adds inlined response examples for POST (201), GET (200), PUT (200),
and GET `_find` (200)

All examples tested against a live Kibana 9.4.0 instance using the
Kibana sample logs dataset (`kibana_sample_data_logs`). Follows the grid
best practices documented in the tag description (PR elastic#262396).

Part of the Dashboards API documentation series: elastic#262396 (merged) →
descriptions (elastic#263166, elastic#263281, elastic#263282, elastic#263283) → this PR.

## Preview

https://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards

## Test plan

- [ ] Generate Bump preview and verify code samples appear in upper
right dropdown for each endpoint
- [ ] Verify response examples appear in the Responses section
- [ ] Confirm all JSON in code samples is fully expanded (no inline
objects)

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

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
(cherry picked from commit f6059b0)
kibanamachine added a commit that referenced this pull request Apr 16, 2026
@kibanamachine @florent-leborgne @claude
[9.4] [Docs][Dashboards API] Add request and response examples for al…
e75785d 
…l 5 endpoints (#262865) (#263899)

# Backport

This will backport the following commits from `main` to `9.4`:
- [[Docs][Dashboards API] Add request and response examples for all 5
endpoints (#262865)](#262865)

<!--- 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-16T20:16:43Z","message":"[Docs][Dashboards
API] Add request and response examples for all 5 endpoints
(#262865)\n\n## Summary\n\n- Adds cURL and Console code samples
(`x-codeSamples`) to all 5\nDashboards API endpoints (POST, GET `/{id}`,
PUT `/{id}`, DELETE\n`/{id}`, GET `_find`)\n- POST includes two
examples: simple dashboard (markdown + 2 metrics +\nES|QL line chart)
and a structured dashboard with sections and controls\n- Adds inlined
response examples for POST (201), GET (200), PUT (200),\nand GET `_find`
(200)\n\nAll examples tested against a live Kibana 9.4.0 instance using
the\nKibana sample logs dataset (`kibana_sample_data_logs`). Follows the
grid\nbest practices documented in the tag description (PR
#262396).\n\nPart of the Dashboards API documentation series: #262396
(merged) →\ndescriptions (#263166, #263281, #263282, #263283) → this
PR.\n\n##
Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards\n\n##
Test plan\n\n- [ ] Generate Bump preview and verify code samples appear
in upper\nright dropdown for each endpoint\n- [ ] Verify response
examples appear in the Responses section\n- [ ] Confirm all JSON in code
samples is fully expanded (no inline\nobjects)\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>","sha":"f6059b02aca72b0978a1da87a5c74ccb60e26325","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][Dashboards
API] Add request and response examples for all 5
endpoints","number":262865,"url":"https://github.com/elastic/kibana/pull/262865","mergeCommit":{"message":"[Docs][Dashboards
API] Add request and response examples for all 5 endpoints
(#262865)\n\n## Summary\n\n- Adds cURL and Console code samples
(`x-codeSamples`) to all 5\nDashboards API endpoints (POST, GET `/{id}`,
PUT `/{id}`, DELETE\n`/{id}`, GET `_find`)\n- POST includes two
examples: simple dashboard (markdown + 2 metrics +\nES|QL line chart)
and a structured dashboard with sections and controls\n- Adds inlined
response examples for POST (201), GET (200), PUT (200),\nand GET `_find`
(200)\n\nAll examples tested against a live Kibana 9.4.0 instance using
the\nKibana sample logs dataset (`kibana_sample_data_logs`). Follows the
grid\nbest practices documented in the tag description (PR
#262396).\n\nPart of the Dashboards API documentation series: #262396
(merged) →\ndescriptions (#263166, #263281, #263282, #263283) → this
PR.\n\n##
Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards\n\n##
Test plan\n\n- [ ] Generate Bump preview and verify code samples appear
in upper\nright dropdown for each endpoint\n- [ ] Verify response
examples appear in the Responses section\n- [ ] Confirm all JSON in code
samples is fully expanded (no inline\nobjects)\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>","sha":"f6059b02aca72b0978a1da87a5c74ccb60e26325"}},"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/262865","number":262865,"mergeCommit":{"message":"[Docs][Dashboards
API] Add request and response examples for all 5 endpoints
(#262865)\n\n## Summary\n\n- Adds cURL and Console code samples
(`x-codeSamples`) to all 5\nDashboards API endpoints (POST, GET `/{id}`,
PUT `/{id}`, DELETE\n`/{id}`, GET `_find`)\n- POST includes two
examples: simple dashboard (markdown + 2 metrics +\nES|QL line chart)
and a structured dashboard with sections and controls\n- Adds inlined
response examples for POST (201), GET (200), PUT (200),\nand GET `_find`
(200)\n\nAll examples tested against a live Kibana 9.4.0 instance using
the\nKibana sample logs dataset (`kibana_sample_data_logs`). Follows the
grid\nbest practices documented in the tag description (PR
#262396).\n\nPart of the Dashboards API documentation series: #262396
(merged) →\ndescriptions (#263166, #263281, #263282, #263283) → this
PR.\n\n##
Preview\n\n\nhttps://bump.sh/elastic/hub/elastic-apis/doc/dashboards-api-cleanup-intro-and-get-started/group/endpoint-dashboards\n\n##
Test plan\n\n- [ ] Generate Bump preview and verify code samples appear
in upper\nright dropdown for each endpoint\n- [ ] Verify response
examples appear in the Responses section\n- [ ] Confirm all JSON in code
samples is fully expanded (no inline\nobjects)\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>","sha":"f6059b02aca72b0978a1da87a5c74ccb60e26325"}}]}]
BACKPORT-->

Co-authored-by: Florent LB <florent.leborgne@elastic.co>
Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
davismcphee
davismcphee approved these changes Apr 16, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@davismcphee davismcphee left a comment

Choose a reason for hiding this comment

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

Code-only review, Data Discovery changes LGTM 👍

@florent-leborgne florent-leborgne merged commit b066d86 into main Apr 17, 2026
20 checks passed
@florent-leborgne florent-leborgne deleted the dashboards-api-docs-2b branch April 17, 2026 09:03
@kibanamachine
Copy link
Copy Markdown
Contributor

kibanamachine commented Apr 17, 2026

Starting backport for target branches: 9.4

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

kibanamachine pushed a commit to kibanamachine/kibana that referenced this pull request Apr 17, 2026
@florent-leborgne @claude
[Docs][Dashboards API] Add field descriptions to timeRangeSchema and …
aaa2948 
…refreshIntervalSchema (elastic#263281)

## Summary

Adds API-agnostic field descriptions to two shared schema files used as
`$ref` components by the Dashboards API (and other APIs including Maps
and ML):

- **`kbn-es-query-server` — `timeRangeSchema`**: descriptions for
`from`, `to`, and `mode` fields with [date
math](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math)
links; `title` meta on `absolute`/`relative` variants; object-level
`title` and `description`.
- **`kbn-data-service-server` — `refreshIntervalSchema`**: fixed
inverted `pause` description; improved `value` description; object-level
`title` and `description`.

All descriptions are API-agnostic and follow the shared schema style
rules.

## Test plan

- [x] ESLint passes on both files
- [x] Descriptions render 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>
(cherry picked from commit b066d86)
@kibanamachine kibanamachine mentioned this pull request Apr 17, 2026
Merged
@kibanamachine
Copy link
Copy Markdown
Contributor

kibanamachine commented Apr 17, 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 17, 2026
@kibanamachine @florent-leborgne @claude
[9.4] [Docs][Dashboards API] Add field descriptions to timeRangeSchem…
a84c4d5 
…a and refreshIntervalSchema (#263281) (#263997)

# Backport

This will backport the following commits from `main` to `9.4`:
- [[Docs][Dashboards API] Add field descriptions to timeRangeSchema and
refreshIntervalSchema
(#263281)](#263281)

<!--- 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-17T09:03:24Z","message":"[Docs][Dashboards
API] Add field descriptions to timeRangeSchema and refreshIntervalSchema
(#263281)\n\n## Summary\n\nAdds API-agnostic field descriptions to two
shared schema files used as\n`$ref` components by the Dashboards API
(and other APIs including Maps\nand ML):\n\n- **`kbn-es-query-server` —
`timeRangeSchema`**: descriptions for\n`from`, `to`, and `mode` fields
with
[date\nmath](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math)\nlinks;
`title` meta on `absolute`/`relative` variants; object-level\n`title`
and `description`.\n- **`kbn-data-service-server` —
`refreshIntervalSchema`**: fixed\ninverted `pause` description; improved
`value` description; object-level\n`title` and `description`.\n\nAll
descriptions are API-agnostic and follow the shared schema
style\nrules.\n\n## Test plan\n\n- [x] ESLint passes on both files\n-
[x] Descriptions render 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>","sha":"b066d8690ccf05e32b96203de9e4a35c28050823","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][Dashboards
API] Add field descriptions to timeRangeSchema and
refreshIntervalSchema","number":263281,"url":"https://github.com/elastic/kibana/pull/263281","mergeCommit":{"message":"[Docs][Dashboards
API] Add field descriptions to timeRangeSchema and refreshIntervalSchema
(#263281)\n\n## Summary\n\nAdds API-agnostic field descriptions to two
shared schema files used as\n`$ref` components by the Dashboards API
(and other APIs including Maps\nand ML):\n\n- **`kbn-es-query-server` —
`timeRangeSchema`**: descriptions for\n`from`, `to`, and `mode` fields
with
[date\nmath](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math)\nlinks;
`title` meta on `absolute`/`relative` variants; object-level\n`title`
and `description`.\n- **`kbn-data-service-server` —
`refreshIntervalSchema`**: fixed\ninverted `pause` description; improved
`value` description; object-level\n`title` and `description`.\n\nAll
descriptions are API-agnostic and follow the shared schema
style\nrules.\n\n## Test plan\n\n- [x] ESLint passes on both files\n-
[x] Descriptions render 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>","sha":"b066d8690ccf05e32b96203de9e4a35c28050823"}},"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/263281","number":263281,"mergeCommit":{"message":"[Docs][Dashboards
API] Add field descriptions to timeRangeSchema and refreshIntervalSchema
(#263281)\n\n## Summary\n\nAdds API-agnostic field descriptions to two
shared schema files used as\n`$ref` components by the Dashboards API
(and other APIs including Maps\nand ML):\n\n- **`kbn-es-query-server` —
`timeRangeSchema`**: descriptions for\n`from`, `to`, and `mode` fields
with
[date\nmath](https://www.elastic.co/docs/reference/elasticsearch/rest-apis/common-options#date-math)\nlinks;
`title` meta on `absolute`/`relative` variants; object-level\n`title`
and `description`.\n- **`kbn-data-service-server` —
`refreshIntervalSchema`**: fixed\ninverted `pause` description; improved
`value` description; object-level\n`title` and `description`.\n\nAll
descriptions are API-agnostic and follow the shared schema
style\nrules.\n\n## Test plan\n\n- [x] ESLint passes on both files\n-
[x] Descriptions render 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>","sha":"b066d8690ccf05e32b96203de9e4a35c28050823"}}]}]
BACKPORT-->

Co-authored-by: Florent LB <florent.leborgne@elastic.co>
Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.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

@davismcphee davismcphee davismcphee approved these changes

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.

5 participants

@florent-leborgne @elasticmachine @kibanamachine @nreese @davismcphee