add @doc comments for remaining fields in APIMetadata, update CLAUDE.md to execute verification of ./build-schema command for all 4 schema types (gcp+core)

Author: mliptak0

CLAUDE.md

@@ -13,10 +13,12 @@ npm run build:all           # Generate all variants with Swagger
 
 **Validation workflow:**
 ```bash
-npm install                 # Install dependencies
-npm run build:core         # Build and verify compilation
-npm run build:gcp          # Build GCP variant
-ls -l schemas/*/openapi.yaml  # Confirm outputs exist
+npm install                              # Install dependencies
+./build-schema.sh gcp                   # Build GCP OpenAPI 3.0
+./build-schema.sh gcp --swagger         # Build GCP OpenAPI 2.0 (Swagger)
+./build-schema.sh core                  # Build core OpenAPI 3.0
+./build-schema.sh core --swagger        # Build core OpenAPI 2.0 (Swagger)
+ls -l schemas/*/openapi.yaml            # Confirm outputs exist
 ```
 
 ## Key Concepts
@@ -98,7 +100,11 @@ services/
 - Commit `node_modules/` or build artifacts
 
 **DO:**
-- Run `npm run build:all` before committing schema changes
+- Run builds in this order before committing schema changes:
+  1. `./build-schema.sh gcp`
+  2. `./build-schema.sh gcp --swagger`
+  3. `./build-schema.sh core`
+  4. `./build-schema.sh core --swagger`
 - Test both provider variants when modifying shared models
 - Keep TypeSpec files focused (one resource per service file)
 - Use semantic versioning for releases (see RELEASING.md)
@@ -187,8 +193,10 @@ Build: `npm run build:gcp`
 Before submitting changes:
 
 - [ ] Dependencies installed: `npm install`
-- [ ] Core variant builds: `npm run build:core`
-- [ ] GCP variant builds: `npm run build:gcp`
+- [ ] GCP variant builds: `./build-schema.sh gcp`
+- [ ] GCP Swagger builds: `./build-schema.sh gcp --swagger`
+- [ ] Core variant builds: `./build-schema.sh core`
+- [ ] Core Swagger builds: `./build-schema.sh core --swagger`
 - [ ] Schema files generated: `ls schemas/*/openapi.yaml`
 - [ ] No TypeSpec compilation errors (check output)
 - [ ] Changes committed including schema updates

models/common/model.tsp

@@ -112,14 +112,21 @@ model APIResource {
     labels?: Record<string>;
 }
 model APIMetadata {
+    @doc("Timestamp when the resource was created")
     @format("date-time") created_time: string;
+
+    @doc("Timestamp when the resource was last updated")
     @format("date-time") updated_time: string;
+
+    @doc("Identity that created the resource")
     @format("email") created_by: string;
+
+    @doc("Identity that last updated the resource")
     @format("email") updated_by: string;
 
     @doc("Timestamp when deletion was requested; omitted if not marked for deletion")
     @format("date-time") deleted_time?: string;
-    
+
     @doc("Identity that requested deletion; omitted if not marked for deletion")
     @format("email") deleted_by?: string;
 }

schemas/core/openapi.yaml

@@ -910,15 +910,19 @@ components:
         created_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was created
         updated_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was last updated
         created_by:
           type: string
           format: email
+          description: Identity that created the resource
         updated_by:
           type: string
           format: email
+          description: Identity that last updated the resource
         deleted_time:
           type: string
           format: date-time
@@ -1175,15 +1179,19 @@ components:
         created_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was created
         updated_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was last updated
         created_by:
           type: string
           format: email
+          description: Identity that created the resource
         updated_by:
           type: string
           format: email
+          description: Identity that last updated the resource
         deleted_time:
           type: string
           format: date-time
@@ -1325,15 +1333,19 @@ components:
         created_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was created
         updated_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was last updated
         created_by:
           type: string
           format: email
+          description: Identity that created the resource
         updated_by:
           type: string
           format: email
+          description: Identity that last updated the resource
         deleted_time:
           type: string
           format: date-time

schemas/core/swagger.yaml

@@ -1076,9 +1076,11 @@ definitions:
       updated_time: '2021-01-01T10:02:00Z'
     properties:
       created_by:
+        description: Identity that created the resource
         format: email
         type: string
       created_time:
+        description: Timestamp when the resource was created
         format: date-time
         type: string
       deleted_by:
@@ -1123,9 +1125,11 @@ definitions:
       status:
         $ref: '#/definitions/ClusterStatus'
       updated_by:
+        description: Identity that last updated the resource
         format: email
         type: string
       updated_time:
+        description: Timestamp when the resource was last updated
         format: date-time
         type: string
     required:
@@ -1362,9 +1366,11 @@ definitions:
       updated_time: '2021-01-01T10:02:00Z'
     properties:
       created_by:
+        description: Identity that created the resource
         format: email
         type: string
       created_time:
+        description: Timestamp when the resource was created
         format: date-time
         type: string
       deleted_by:
@@ -1411,9 +1417,11 @@ definitions:
       status:
         $ref: '#/definitions/NodePoolStatus'
       updated_by:
+        description: Identity that last updated the resource
         format: email
         type: string
       updated_time:
+        description: Timestamp when the resource was last updated
         format: date-time
         type: string
     required:
@@ -1464,9 +1472,11 @@ definitions:
   NodePoolCreateResponse:
     properties:
       created_by:
+        description: Identity that created the resource
         format: email
         type: string
       created_time:
+        description: Timestamp when the resource was created
         format: date-time
         type: string
       deleted_by:
@@ -1513,9 +1523,11 @@ definitions:
       status:
         $ref: '#/definitions/NodePoolStatus'
       updated_by:
+        description: Identity that last updated the resource
         format: email
         type: string
       updated_time:
+        description: Timestamp when the resource was last updated
         format: date-time
         type: string
     required:

schemas/gcp/openapi.yaml

@@ -827,15 +827,19 @@ components:
         created_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was created
         updated_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was last updated
         created_by:
           type: string
           format: email
+          description: Identity that created the resource
         updated_by:
           type: string
           format: email
+          description: Identity that last updated the resource
         deleted_time:
           type: string
           format: date-time
@@ -1170,15 +1174,19 @@ components:
         created_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was created
         updated_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was last updated
         created_by:
           type: string
           format: email
+          description: Identity that created the resource
         updated_by:
           type: string
           format: email
+          description: Identity that last updated the resource
         deleted_time:
           type: string
           format: date-time
@@ -1358,15 +1366,19 @@ components:
         created_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was created
         updated_time:
           type: string
           format: date-time
+          description: Timestamp when the resource was last updated
         created_by:
           type: string
           format: email
+          description: Identity that created the resource
         updated_by:
           type: string
           format: email
+          description: Identity that last updated the resource
         deleted_time:
           type: string
           format: date-time

schemas/gcp/swagger.yaml

@@ -994,9 +994,11 @@ definitions:
       updated_time: '2021-01-01T10:02:00Z'
     properties:
       created_by:
+        description: Identity that created the resource
         format: email
         type: string
       created_time:
+        description: Timestamp when the resource was created
         format: date-time
         type: string
       deleted_by:
@@ -1041,9 +1043,11 @@ definitions:
       status:
         $ref: '#/definitions/ClusterStatus'
       updated_by:
+        description: Identity that last updated the resource
         format: email
         type: string
       updated_time:
+        description: Timestamp when the resource was last updated
         format: date-time
         type: string
     required:
@@ -1356,9 +1360,11 @@ definitions:
       updated_time: '2021-01-01T10:02:00Z'
     properties:
       created_by:
+        description: Identity that created the resource
         format: email
         type: string
       created_time:
+        description: Timestamp when the resource was created
         format: date-time
         type: string
       deleted_by:
@@ -1405,9 +1411,11 @@ definitions:
       status:
         $ref: '#/definitions/NodePoolStatus'
       updated_by:
+        description: Identity that last updated the resource
         format: email
         type: string
       updated_time:
+        description: Timestamp when the resource was last updated
         format: date-time
         type: string
     required:
@@ -1477,9 +1485,11 @@ definitions:
   NodePoolCreateResponse:
     properties:
       created_by:
+        description: Identity that created the resource
         format: email
         type: string
       created_time:
+        description: Timestamp when the resource was created
         format: date-time
         type: string
       deleted_by:
@@ -1526,9 +1536,11 @@ definitions:
       status:
         $ref: '#/definitions/NodePoolStatus'
       updated_by:
+        description: Identity that last updated the resource
         format: email
         type: string
       updated_time:
+        description: Timestamp when the resource was last updated
         format: date-time
         type: string
     required: