Refactor theme validation to use catalog schema reference

specification/v0_10/docs/a2ui_protocol.md

@@ -137,11 +137,11 @@ The [`server_to_client.json`] schema is the top-level entry point. Every message
 
 ### The Standard Catalog
 
-The [`standard_catalog.json`] schema contains the definitions for all specific UI components (e.g., `Text`, `Button`, `Row`) and functions (e.g., `required`, `email`).
+The [`standard_catalog.json`] schema contains the definitions for all specific UI components (e.g., `Text`, `Button`, `Row`), functions (e.g., `required`, `email`), and the theme schema.
 
 **Swappable Catalogs & Validation:**
 
-The [`server_to_client.json`] envelope schema is designed to be catalog-agnostic. It references components using a placeholder filename: `catalog.json` (specifically `$ref: "catalog.json#/$defs/anyComponent"`).
+The [`server_to_client.json`] envelope schema is designed to be catalog-agnostic. It references components and themes using a placeholder filename: `catalog.json` (specifically `$ref: "catalog.json#/$defs/anyComponent"` and `$ref: "catalog.json#/$defs/theme"`).
 
 To validate A2UI messages:
 

specification/v0_10/json/server_to_client.json

@@ -30,9 +30,8 @@
               "type": "string"
             },
             "theme": {
-              "type": "object",
-              "description": "Initial theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog.",
-              "additionalProperties": true
+              "$ref": "catalog.json#/$defs/theme",
+              "description": "Initial theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog."
             },
             "sendDataModel": {
               "type": "boolean",

specification/v0_10/json/standard_catalog.json

@@ -1065,22 +1065,6 @@
       "unevaluatedProperties": false
     }
   },
-  "theme": {
-    "primaryColor": {
-      "type": "string",
-      "description": "The primary brand color used for highlights (e.g., primary buttons, active borders). Renderers may generate variants of this color for different contexts. Format: Hexadecimal code (e.g., '#00BFFF').",
-      "pattern": "^#[0-9a-fA-F]{6}$"
-    },
-    "iconUrl": {
-      "type": "string",
-      "format": "uri",
-      "description": "A URL for an image that identifies the agent or tool associated with the surface."
-    },
-    "agentDisplayName": {
-      "type": "string",
-      "description": "Text to be displayed next to the surface to identify the agent or tool that created it."
-    }
-  },
   "$defs": {
     "CatalogComponentCommon": {
       "type": "object",
@@ -1091,6 +1075,26 @@
         }
       }
     },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "primaryColor": {
+          "type": "string",
+          "description": "The primary brand color used for highlights (e.g., primary buttons, active borders). Renderers may generate variants of this color for different contexts. Format: Hexadecimal code (e.g., '#00BFFF').",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "iconUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "A URL for an image that identifies the agent or tool associated with the surface."
+        },
+        "agentDisplayName": {
+          "type": "string",
+          "description": "Text to be displayed next to the surface to identify the agent or tool that created it."
+        }
+      },
+      "additionalProperties": true
+    },
     "anyComponent": {
       "oneOf": [
         { "$ref": "#/components/Text" },

specification/v0_10/test/cases/theme_validation.json

@@ -0,0 +1,63 @@
+{
+  "schema": "server_to_client.json",
+  "tests": [
+    {
+      "description": "Valid theme in createSurface",
+      "valid": true,
+      "data": {
+        "version": "v0.10",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
+          "theme": {
+            "primaryColor": "#00BFFF",
+            "agentDisplayName": "Test Agent"
+          }
+        }
+      }
+    },
+    {
+      "description": "Invalid theme property (wrong type)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
+          "theme": {
+            "primaryColor": 123
+          }
+        }
+      }
+    },
+    {
+      "description": "Invalid theme property (invalid hex color)",
+      "valid": false,
+      "data": {
+        "version": "v0.10",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
+          "theme": {
+            "primaryColor": "invalid-color"
+          }
+        }
+      }
+    },
+    {
+      "description": "Additional theme properties are allowed",
+      "valid": true,
+      "data": {
+        "version": "v0.10",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
+          "theme": {
+            "primaryColor": "#00BFFF",
+            "customProperty": "customValue"
+          }
+        }
+      }
+    }
+  ]
+}

specification/v0_9/docs/a2ui_protocol.md

@@ -142,11 +142,11 @@ The [`server_to_client.json`] schema is the top-level entry point. Every message
 
 ### The Standard Catalog
 
-The [`standard_catalog.json`] schema contains the definitions for all specific UI components (e.g., `Text`, `Button`, `Row`) and functions (e.g., `required`, `email`).
+The [`standard_catalog.json`] schema contains the definitions for all specific UI components (e.g., `Text`, `Button`, `Row`), functions (e.g., `required`, `email`), and the theme schema.
 
 **Swappable Catalogs & Validation:**
 
-The [`server_to_client.json`] envelope schema is designed to be catalog-agnostic. It references components using a placeholder filename: `catalog.json` (specifically `$ref: "catalog.json#/$defs/anyComponent"`).
+The [`server_to_client.json`] envelope schema is designed to be catalog-agnostic. It references components and themes using a placeholder filename: `catalog.json` (specifically `$ref: "catalog.json#/$defs/anyComponent"` and `$ref: "catalog.json#/$defs/theme"`).
 
 To validate A2UI messages:
 

specification/v0_9/json/server_to_client.json

@@ -30,9 +30,8 @@
               "type": "string"
             },
             "theme": {
-              "type": "object",
-              "description": "Initial theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog.",
-              "additionalProperties": true
+              "$ref": "catalog.json#/$defs/theme",
+              "description": "Theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog."
             },
             "sendDataModel": {
               "type": "boolean",

specification/v0_9/json/standard_catalog.json

@@ -1224,22 +1224,6 @@
       "unevaluatedProperties": false
     }
   },
-  "theme": {
-    "primaryColor": {
-      "type": "string",
-      "description": "The primary brand color used for highlights (e.g., primary buttons, active borders). Renderers may generate variants of this color for different contexts. Format: Hexadecimal code (e.g., '#00BFFF').",
-      "pattern": "^#[0-9a-fA-F]{6}$"
-    },
-    "iconUrl": {
-      "type": "string",
-      "format": "uri",
-      "description": "A URL for an image that identifies the agent or tool associated with the surface."
-    },
-    "agentDisplayName": {
-      "type": "string",
-      "description": "Text to be displayed next to the surface to identify the agent or tool that created it."
-    }
-  },
   "$defs": {
     "CatalogComponentCommon": {
       "type": "object",
@@ -1250,6 +1234,26 @@
         }
       }
     },
+    "theme": {
+      "type": "object",
+      "properties": {
+        "primaryColor": {
+          "type": "string",
+          "description": "The primary brand color used for highlights (e.g., primary buttons, active borders). Renderers may generate variants of this color for different contexts. Format: Hexadecimal code (e.g., '#00BFFF').",
+          "pattern": "^#[0-9a-fA-F]{6}$"
+        },
+        "iconUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "A URL for an image that identifies the agent or tool associated with the surface."
+        },
+        "agentDisplayName": {
+          "type": "string",
+          "description": "Text to be displayed next to the surface to identify the agent or tool that created it."
+        }
+      },
+      "additionalProperties": true
+    },
     "anyComponent": {
       "oneOf": [
         {

specification/v0_9/test/cases/theme_validation.json

@@ -0,0 +1,63 @@
+{
+  "schema": "server_to_client.json",
+  "tests": [
+    {
+      "description": "Valid theme in createSurface",
+      "valid": true,
+      "data": {
+        "version": "v0.9",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
+          "theme": {
+            "primaryColor": "#00BFFF",
+            "agentDisplayName": "Test Agent"
+          }
+        }
+      }
+    },
+    {
+      "description": "Invalid theme property (wrong type)",
+      "valid": false,
+      "data": {
+        "version": "v0.9",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
+          "theme": {
+            "primaryColor": 123
+          }
+        }
+      }
+    },
+    {
+      "description": "Invalid theme property (invalid hex color)",
+      "valid": false,
+      "data": {
+        "version": "v0.9",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
+          "theme": {
+            "primaryColor": "invalid-color"
+          }
+        }
+      }
+    },
+    {
+      "description": "Additional theme properties are allowed",
+      "valid": true,
+      "data": {
+        "version": "v0.9",
+        "createSurface": {
+          "surfaceId": "test_surface",
+          "catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
+          "theme": {
+            "primaryColor": "#00BFFF",
+            "customProperty": "customValue"
+          }
+        }
+      }
+    }
+  ]
+}