Skip to content

Conversation

lcawl
Copy link
Contributor

@lcawl lcawl commented Oct 3, 2025

This PR adds an overlay to change the definition for the Duration data type in the OpenAPI files that are used for docs.

It was:

      "_types.Duration": {
        "description": "A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and\n`d` (days). Also accepts \"0\" without a unit and \"-1\" to indicate an unspecified value.",
        "oneOf": [
          {
            "type": "string"
          },
          {
            "type": "string",
            "enum": [
              "-1"
            ]
          },
          {
            "type": "string",
            "enum": [
              "0"
            ]
          }
        ]
      },

This PR changes it to:

      "_types.Duration": {
        "description": "A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and\n`d` (days). Also accepts \"0\" without a unit and \"-1\" to indicate an unspecified value.",
        "type": "string"
      },

The reason for the change is that the way it's currently rendered in the documentation, it looks like "-1" and "0" are the only valid options:

image

For example in https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze

With this overlay in place, the output is as follows:

image

Copy link
Contributor

github-actions bot commented Oct 3, 2025

Following you can find the validation changes against the target branch for the APIs.

No changes detected.

You can validate these APIs yourself by using the make validate target.

@lcawl lcawl requested a review from a team October 3, 2025 19:49
@lcawl lcawl marked this pull request as ready for review October 3, 2025 19:49
Copy link
Contributor

@leemthompo leemthompo left a comment

Choose a reason for hiding this comment

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

Preview looks good to me, but I guess it would be nice to indicate potential valid values, but sounds like a can of worms per the Slack discussion. It's at least nice to remove the implication that it only accepts -1 or 0.

@lcawl lcawl merged commit 1c92db2 into main Oct 6, 2025
14 checks passed
@lcawl lcawl deleted the duration-overlay branch October 6, 2025 15:26
github-actions bot pushed a commit that referenced this pull request Oct 6, 2025
github-actions bot pushed a commit that referenced this pull request Oct 6, 2025
lcawl added a commit that referenced this pull request Oct 6, 2025
(cherry picked from commit 1c92db2)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
github-actions bot pushed a commit that referenced this pull request Oct 6, 2025
lcawl added a commit that referenced this pull request Oct 6, 2025
(cherry picked from commit 1c92db2)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
github-actions bot pushed a commit that referenced this pull request Oct 6, 2025
lcawl added a commit that referenced this pull request Oct 6, 2025
(cherry picked from commit 1c92db2)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
lcawl added a commit that referenced this pull request Oct 6, 2025
(cherry picked from commit 1c92db2)

Co-authored-by: Lisa Cawley <lcawley@elastic.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants