diff --git a/specification/v0_10/docs/a2ui_protocol.md b/specification/v0_10/docs/a2ui_protocol.md index 52da38a9..75220cd8 100644 --- a/specification/v0_10/docs/a2ui_protocol.md +++ b/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: diff --git a/specification/v0_10/json/server_to_client.json b/specification/v0_10/json/server_to_client.json index 835786fb..9e393c18 100644 --- a/specification/v0_10/json/server_to_client.json +++ b/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", diff --git a/specification/v0_10/json/standard_catalog.json b/specification/v0_10/json/standard_catalog.json index 076f9ef6..7e297300 100644 --- a/specification/v0_10/json/standard_catalog.json +++ b/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" }, diff --git a/specification/v0_10/test/cases/theme_validation.json b/specification/v0_10/test/cases/theme_validation.json new file mode 100644 index 00000000..4a01bce5 --- /dev/null +++ b/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" + } + } + } + } + ] +} diff --git a/specification/v0_9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md index 910be0e4..fca2262b 100644 --- a/specification/v0_9/docs/a2ui_protocol.md +++ b/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: diff --git a/specification/v0_9/json/server_to_client.json b/specification/v0_9/json/server_to_client.json index 3ae12421..921e4168 100644 --- a/specification/v0_9/json/server_to_client.json +++ b/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", diff --git a/specification/v0_9/json/standard_catalog.json b/specification/v0_9/json/standard_catalog.json index 575ed2f3..32c780de 100644 --- a/specification/v0_9/json/standard_catalog.json +++ b/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": [ { diff --git a/specification/v0_9/test/cases/theme_validation.json b/specification/v0_9/test/cases/theme_validation.json new file mode 100644 index 00000000..bc56f1fa --- /dev/null +++ b/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" + } + } + } + } + ] +}