From 06743b0b3158db4360b775055279fc3b3c75212c Mon Sep 17 00:00:00 2001
From: David Crespo <david-crespo@users.noreply.github.com>
Date: Wed, 26 Jun 2024 15:48:30 -0500
Subject: [PATCH] Put max length in `Name` description (#5958)

Closes #5940. This is hack around a current limitation of the docs site,
namely that we do not show meta constraints like `maxLength` on types.
Because the regex pattern for `Name` is gnarly and unreadable, we
already rely on the description to give users a sense of the
requirements. This change adds max length to that description.

I updated everything but the Nexus OpenAPI schema manually with
find/replace, so I will see from CI whether I got that right.

<img width="962" alt="image"
src="https://github.com/oxidecomputer/omicron/assets/3612203/aed40498-9f60-41b6-95f2-fda050873540">
---
 common/src/api/external/mod.rs            | 4 ++--
 common/tests/output/pagination-schema.txt | 4 ++--
 openapi/bootstrap-agent.json              | 4 ++--
 openapi/nexus-internal.json               | 4 ++--
 openapi/nexus.json                        | 4 ++--
 openapi/sled-agent.json                   | 2 +-
 openapi/wicketd.json                      | 2 +-
 schema/all-zones-requests.json            | 2 +-
 schema/rss-service-plan-v2.json           | 2 +-
 schema/rss-service-plan-v3.json           | 2 +-
 schema/rss-sled-plan.json                 | 4 ++--
 11 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/common/src/api/external/mod.rs b/common/src/api/external/mod.rs
index 58d45fecef..158b087a5c 100644
--- a/common/src/api/external/mod.rs
+++ b/common/src/api/external/mod.rs
@@ -305,8 +305,8 @@ impl JsonSchema for Name {
                     "Names must begin with a lower case ASCII letter, be \
                      composed exclusively of lowercase ASCII, uppercase \
                      ASCII, numbers, and '-', and may not end with a '-'. \
-                     Names cannot be a UUID though they may contain a UUID."
-                        .to_string(),
+                     Names cannot be a UUID, but they may contain a UUID. \
+                     They can be at most 63 characters long.".to_string(),
                 ),
                 ..Default::default()
             })),
diff --git a/common/tests/output/pagination-schema.txt b/common/tests/output/pagination-schema.txt
index 436e614994..9da2fffc26 100644
--- a/common/tests/output/pagination-schema.txt
+++ b/common/tests/output/pagination-schema.txt
@@ -135,7 +135,7 @@ schema for pagination parameters: page selector, scan by name only
   "definitions": {
     "Name": {
       "title": "A name unique within the parent collection",
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
       "type": "string",
       "maxLength": 63,
       "minLength": 1,
@@ -224,7 +224,7 @@ schema for pagination parameters: page selector, scan by name or id
   "definitions": {
     "Name": {
       "title": "A name unique within the parent collection",
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
       "type": "string",
       "maxLength": 63,
       "minLength": 1,
diff --git a/openapi/bootstrap-agent.json b/openapi/bootstrap-agent.json
index 6050939b94..370f0fb404 100644
--- a/openapi/bootstrap-agent.json
+++ b/openapi/bootstrap-agent.json
@@ -734,7 +734,7 @@
       },
       "Name": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
@@ -1254,7 +1254,7 @@
         ]
       },
       "UserId": {
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.\n\n<details><summary>JSON schema</summary>\n\n```json { \"title\": \"A name unique within the parent collection\", \"description\": \"Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.\", \"type\": \"string\", \"maxLength\": 63, \"minLength\": 1, \"pattern\": \"^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$\" } ``` </details>",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.\n\n<details><summary>JSON schema</summary>\n\n```json { \"title\": \"A name unique within the parent collection\", \"description\": \"Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.\", \"type\": \"string\", \"maxLength\": 63, \"minLength\": 1, \"pattern\": \"^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$\" } ``` </details>",
         "type": "string"
       }
     },
diff --git a/openapi/nexus-internal.json b/openapi/nexus-internal.json
index 72731e83e8..d479e2e20c 100644
--- a/openapi/nexus-internal.json
+++ b/openapi/nexus-internal.json
@@ -3526,7 +3526,7 @@
       },
       "Name": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
@@ -5031,7 +5031,7 @@
       },
       "UserId": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
diff --git a/openapi/nexus.json b/openapi/nexus.json
index f4cd1ce89e..598f0453ff 100644
--- a/openapi/nexus.json
+++ b/openapi/nexus.json
@@ -15786,7 +15786,7 @@
       },
       "Name": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
@@ -18868,7 +18868,7 @@
       },
       "UserId": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
diff --git a/openapi/sled-agent.json b/openapi/sled-agent.json
index 3ac130c565..aa5163a964 100644
--- a/openapi/sled-agent.json
+++ b/openapi/sled-agent.json
@@ -3559,7 +3559,7 @@
       },
       "Name": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
diff --git a/openapi/wicketd.json b/openapi/wicketd.json
index 555b8cf44c..7d50a38268 100644
--- a/openapi/wicketd.json
+++ b/openapi/wicketd.json
@@ -1774,7 +1774,7 @@
       },
       "Name": {
         "title": "A name unique within the parent collection",
-        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+        "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
         "type": "string",
         "pattern": "^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$",
         "minLength": 1,
diff --git a/schema/all-zones-requests.json b/schema/all-zones-requests.json
index 526e41376f..210f1df2f9 100644
--- a/schema/all-zones-requests.json
+++ b/schema/all-zones-requests.json
@@ -105,7 +105,7 @@
     },
     "Name": {
       "title": "A name unique within the parent collection",
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
       "type": "string",
       "maxLength": 63,
       "minLength": 1,
diff --git a/schema/rss-service-plan-v2.json b/schema/rss-service-plan-v2.json
index ee0b21af81..e5aba43040 100644
--- a/schema/rss-service-plan-v2.json
+++ b/schema/rss-service-plan-v2.json
@@ -178,7 +178,7 @@
     },
     "Name": {
       "title": "A name unique within the parent collection",
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
       "type": "string",
       "maxLength": 63,
       "minLength": 1,
diff --git a/schema/rss-service-plan-v3.json b/schema/rss-service-plan-v3.json
index d1540ca351..9348774c35 100644
--- a/schema/rss-service-plan-v3.json
+++ b/schema/rss-service-plan-v3.json
@@ -219,7 +219,7 @@
     },
     "Name": {
       "title": "A name unique within the parent collection",
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
       "type": "string",
       "maxLength": 63,
       "minLength": 1,
diff --git a/schema/rss-sled-plan.json b/schema/rss-sled-plan.json
index a42a22efd8..cb3c5c8eeb 100644
--- a/schema/rss-sled-plan.json
+++ b/schema/rss-sled-plan.json
@@ -606,7 +606,7 @@
     },
     "Name": {
       "title": "A name unique within the parent collection",
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.",
       "type": "string",
       "maxLength": 63,
       "minLength": 1,
@@ -1017,7 +1017,7 @@
       }
     },
     "UserId": {
-      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.\n\n<details><summary>JSON schema</summary>\n\n```json { \"title\": \"A name unique within the parent collection\", \"description\": \"Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID though they may contain a UUID.\", \"type\": \"string\", \"maxLength\": 63, \"minLength\": 1, \"pattern\": \"^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$\" } ``` </details>",
+      "description": "Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.\n\n<details><summary>JSON schema</summary>\n\n```json { \"title\": \"A name unique within the parent collection\", \"description\": \"Names must begin with a lower case ASCII letter, be composed exclusively of lowercase ASCII, uppercase ASCII, numbers, and '-', and may not end with a '-'. Names cannot be a UUID, but they may contain a UUID. They can be at most 63 characters long.\", \"type\": \"string\", \"maxLength\": 63, \"minLength\": 1, \"pattern\": \"^(?![0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$)^[a-z]([a-zA-Z0-9-]*[a-zA-Z0-9]+)?$\" } ``` </details>",
       "type": "string"
     }
   }