From c3454d0f7abfe113c5ba60f2aa3994e9afa8a6b3 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Mon, 6 Oct 2025 10:40:50 -0700
Subject: [PATCH] Add external docs link from Duration to time unit API
 conventions (#5409)

(cherry picked from commit 21acd7707a037fb9800f3f0e4e2695f8e8af3daa)
---
 output/openapi/elasticsearch-openapi.json            |  3 +++
 output/openapi/elasticsearch-serverless-openapi.json |  3 +++
 output/schema/schema.json                            | 10 ++++++----
 specification/_doc_ids/table.csv                     |  1 +
 specification/_types/Time.ts                         |  1 +
 5 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json
index 6db0abd5fa..6034881431 100644
--- a/output/openapi/elasticsearch-openapi.json
+++ b/output/openapi/elasticsearch-openapi.json
@@ -53178,6 +53178,9 @@
         ]
       },
       "_types.Duration": {
+        "externalDocs": {
+          "url": "https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units"
+        },
         "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": [
           {
diff --git a/output/openapi/elasticsearch-serverless-openapi.json b/output/openapi/elasticsearch-serverless-openapi.json
index 8774e28ea1..00b9bfcfdd 100644
--- a/output/openapi/elasticsearch-serverless-openapi.json
+++ b/output/openapi/elasticsearch-serverless-openapi.json
@@ -29015,6 +29015,9 @@
         ]
       },
       "_types.Duration": {
+        "externalDocs": {
+          "url": "https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units"
+        },
         "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": [
           {
diff --git a/output/schema/schema.json b/output/schema/schema.json
index fc68f81cf6..3e343dea04 100644
--- a/output/schema/schema.json
+++ b/output/schema/schema.json
@@ -51115,11 +51115,13 @@
       "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.",
       "docId": "time-value",
       "docUrl": "https://github.com/elastic/elasticsearch/blob/current/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java",
+      "extDocId": "time-units",
+      "extDocUrl": "https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units",
       "name": {
         "name": "Duration",
         "namespace": "_types"
       },
-      "specLocation": "_types/Time.ts#L52-L58",
+      "specLocation": "_types/Time.ts#L52-L59",
       "type": {
         "kind": "union_of",
         "items": [
@@ -51148,7 +51150,7 @@
         "name": "DurationLarge",
         "namespace": "_types"
       },
-      "specLocation": "_types/Time.ts#L60-L65",
+      "specLocation": "_types/Time.ts#L61-L66",
       "type": {
         "kind": "instance_of",
         "type": {
@@ -51169,7 +51171,7 @@
         "name": "DurationValue",
         "namespace": "_types"
       },
-      "specLocation": "_types/Time.ts#L67-L67",
+      "specLocation": "_types/Time.ts#L68-L68",
       "type": {
         "kind": "instance_of",
         "type": {
@@ -58348,7 +58350,7 @@
         "name": "TimeUnit",
         "namespace": "_types"
       },
-      "specLocation": "_types/Time.ts#L69-L77"
+      "specLocation": "_types/Time.ts#L70-L78"
     },
     {
       "kind": "type_alias",
diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv
index 54c511b5bb..6472bec843 100644
--- a/specification/_doc_ids/table.csv
+++ b/specification/_doc_ids/table.csv
@@ -908,6 +908,7 @@ templating-role-query,https://www.elastic.co/docs/deploy-manage/users-roles/clus
 term-vectors-examples,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/term-vectors-examples,,
 terminate-processor,https://www.elastic.co/docs/reference/enrich-processor/terminate-processor,,
 test-grok-pattern,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-text-structure-test-grok-pattern,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/test-grok-pattern.html,
+time-units,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/api-conventions#time-units,,Time units
 time-value,https://github.com/elastic/elasticsearch/blob/current/libs/core/src/main/java/org/elasticsearch/core/TimeValue.java,,
 time-zone-id,https://docs.oracle.com/javase/8/docs/api/java/time/ZoneId.html,,
 transform-set-upgrade-mode,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-transform-set-upgrade-mode,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/transform-set-upgrade-mode.html,
diff --git a/specification/_types/Time.ts b/specification/_types/Time.ts
index a957c95163..045566eab1 100644
--- a/specification/_types/Time.ts
+++ b/specification/_types/Time.ts
@@ -53,6 +53,7 @@ export type DateFormat = string
  * A duration. Units can be `nanos`, `micros`, `ms` (milliseconds), `s` (seconds), `m` (minutes), `h` (hours) and
  * `d` (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.
  * @doc_id time-value
+ * @ext_doc_id time-units
  */
 // Used to be Time, see ES TimeValue
 export type Duration = string | -1 | 0