Skip to content

Commit a3a96fc

Browse files
jacobsimionatojacobsimionato
authored
Refactor theme validation to use catalog schema reference (#621)
1 parent e186e10 commit a3a96fc

File tree

8 files changed

+174
-42
lines changed

8 files changed

+174
-42
lines changed

‎specification/v0_10/docs/a2ui_protocol.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -137,11 +137,11 @@ The [`server_to_client.json`] schema is the top-level entry point. Every message
137137

138138
### The Standard Catalog
139139

140-
The [`standard_catalog.json`] schema contains the definitions for all specific UI components (e.g., `Text`, `Button`, `Row`) and functions (e.g., `required`, `email`).
140+
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.
141141

142142
**Swappable Catalogs & Validation:**
143143

144-
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"`).
144+
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"`).
145145

146146
To validate A2UI messages:
147147

‎specification/v0_10/json/server_to_client.json‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,8 @@
3030
"type": "string"
3131
},
3232
"theme": {
33-
"type": "object",
34-
"description": "Initial theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog.",
35-
"additionalProperties": true
33+
"$ref": "catalog.json#/$defs/theme",
34+
"description": "Initial theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog."
3635
},
3736
"sendDataModel": {
3837
"type": "boolean",

‎specification/v0_10/json/standard_catalog.json‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1065,22 +1065,6 @@
10651065
"unevaluatedProperties": false
10661066
}
10671067
},
1068-
"theme": {
1069-
"primaryColor": {
1070-
"type": "string",
1071-
"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').",
1072-
"pattern": "^#[0-9a-fA-F]{6}$"
1073-
},
1074-
"iconUrl": {
1075-
"type": "string",
1076-
"format": "uri",
1077-
"description": "A URL for an image that identifies the agent or tool associated with the surface."
1078-
},
1079-
"agentDisplayName": {
1080-
"type": "string",
1081-
"description": "Text to be displayed next to the surface to identify the agent or tool that created it."
1082-
}
1083-
},
10841068
"$defs": {
10851069
"CatalogComponentCommon": {
10861070
"type": "object",
@@ -1091,6 +1075,26 @@
10911075
}
10921076
}
10931077
},
1078+
"theme": {
1079+
"type": "object",
1080+
"properties": {
1081+
"primaryColor": {
1082+
"type": "string",
1083+
"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').",
1084+
"pattern": "^#[0-9a-fA-F]{6}$"
1085+
},
1086+
"iconUrl": {
1087+
"type": "string",
1088+
"format": "uri",
1089+
"description": "A URL for an image that identifies the agent or tool associated with the surface."
1090+
},
1091+
"agentDisplayName": {
1092+
"type": "string",
1093+
"description": "Text to be displayed next to the surface to identify the agent or tool that created it."
1094+
}
1095+
},
1096+
"additionalProperties": true
1097+
},
10941098
"anyComponent": {
10951099
"oneOf": [
10961100
{ "$ref": "#/components/Text" },

‎specification/v0_10/test/cases/theme_validation.json‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
{
2+
"schema": "server_to_client.json",
3+
"tests": [
4+
{
5+
"description": "Valid theme in createSurface",
6+
"valid": true,
7+
"data": {
8+
"version": "v0.10",
9+
"createSurface": {
10+
"surfaceId": "test_surface",
11+
"catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
12+
"theme": {
13+
"primaryColor": "#00BFFF",
14+
"agentDisplayName": "Test Agent"
15+
}
16+
}
17+
}
18+
},
19+
{
20+
"description": "Invalid theme property (wrong type)",
21+
"valid": false,
22+
"data": {
23+
"version": "v0.10",
24+
"createSurface": {
25+
"surfaceId": "test_surface",
26+
"catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
27+
"theme": {
28+
"primaryColor": 123
29+
}
30+
}
31+
}
32+
},
33+
{
34+
"description": "Invalid theme property (invalid hex color)",
35+
"valid": false,
36+
"data": {
37+
"version": "v0.10",
38+
"createSurface": {
39+
"surfaceId": "test_surface",
40+
"catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
41+
"theme": {
42+
"primaryColor": "invalid-color"
43+
}
44+
}
45+
}
46+
},
47+
{
48+
"description": "Additional theme properties are allowed",
49+
"valid": true,
50+
"data": {
51+
"version": "v0.10",
52+
"createSurface": {
53+
"surfaceId": "test_surface",
54+
"catalogId": "https://a2ui.org/specification/v0_10/standard_catalog.json",
55+
"theme": {
56+
"primaryColor": "#00BFFF",
57+
"customProperty": "customValue"
58+
}
59+
}
60+
}
61+
}
62+
]
63+
}

‎specification/v0_9/docs/a2ui_protocol.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,11 +142,11 @@ The [`server_to_client.json`] schema is the top-level entry point. Every message
142142

143143
### The Standard Catalog
144144

145-
The [`standard_catalog.json`] schema contains the definitions for all specific UI components (e.g., `Text`, `Button`, `Row`) and functions (e.g., `required`, `email`).
145+
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.
146146

147147
**Swappable Catalogs & Validation:**
148148

149-
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"`).
149+
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"`).
150150

151151
To validate A2UI messages:
152152

‎specification/v0_9/json/server_to_client.json‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,9 +30,8 @@
3030
"type": "string"
3131
},
3232
"theme": {
33-
"type": "object",
34-
"description": "Initial theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog.",
35-
"additionalProperties": true
33+
"$ref": "catalog.json#/$defs/theme",
34+
"description": "Theme parameters for the surface (e.g., {'primaryColor': '#FF0000'}). These must validate against the 'theme' schema defined in the catalog."
3635
},
3736
"sendDataModel": {
3837
"type": "boolean",

‎specification/v0_9/json/standard_catalog.json‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1224,22 +1224,6 @@
12241224
"unevaluatedProperties": false
12251225
}
12261226
},
1227-
"theme": {
1228-
"primaryColor": {
1229-
"type": "string",
1230-
"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').",
1231-
"pattern": "^#[0-9a-fA-F]{6}$"
1232-
},
1233-
"iconUrl": {
1234-
"type": "string",
1235-
"format": "uri",
1236-
"description": "A URL for an image that identifies the agent or tool associated with the surface."
1237-
},
1238-
"agentDisplayName": {
1239-
"type": "string",
1240-
"description": "Text to be displayed next to the surface to identify the agent or tool that created it."
1241-
}
1242-
},
12431227
"$defs": {
12441228
"CatalogComponentCommon": {
12451229
"type": "object",
@@ -1250,6 +1234,26 @@
12501234
}
12511235
}
12521236
},
1237+
"theme": {
1238+
"type": "object",
1239+
"properties": {
1240+
"primaryColor": {
1241+
"type": "string",
1242+
"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').",
1243+
"pattern": "^#[0-9a-fA-F]{6}$"
1244+
},
1245+
"iconUrl": {
1246+
"type": "string",
1247+
"format": "uri",
1248+
"description": "A URL for an image that identifies the agent or tool associated with the surface."
1249+
},
1250+
"agentDisplayName": {
1251+
"type": "string",
1252+
"description": "Text to be displayed next to the surface to identify the agent or tool that created it."
1253+
}
1254+
},
1255+
"additionalProperties": true
1256+
},
12531257
"anyComponent": {
12541258
"oneOf": [
12551259
{

‎specification/v0_9/test/cases/theme_validation.json‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
{
2+
"schema": "server_to_client.json",
3+
"tests": [
4+
{
5+
"description": "Valid theme in createSurface",
6+
"valid": true,
7+
"data": {
8+
"version": "v0.9",
9+
"createSurface": {
10+
"surfaceId": "test_surface",
11+
"catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
12+
"theme": {
13+
"primaryColor": "#00BFFF",
14+
"agentDisplayName": "Test Agent"
15+
}
16+
}
17+
}
18+
},
19+
{
20+
"description": "Invalid theme property (wrong type)",
21+
"valid": false,
22+
"data": {
23+
"version": "v0.9",
24+
"createSurface": {
25+
"surfaceId": "test_surface",
26+
"catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
27+
"theme": {
28+
"primaryColor": 123
29+
}
30+
}
31+
}
32+
},
33+
{
34+
"description": "Invalid theme property (invalid hex color)",
35+
"valid": false,
36+
"data": {
37+
"version": "v0.9",
38+
"createSurface": {
39+
"surfaceId": "test_surface",
40+
"catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
41+
"theme": {
42+
"primaryColor": "invalid-color"
43+
}
44+
}
45+
}
46+
},
47+
{
48+
"description": "Additional theme properties are allowed",
49+
"valid": true,
50+
"data": {
51+
"version": "v0.9",
52+
"createSurface": {
53+
"surfaceId": "test_surface",
54+
"catalogId": "https://a2ui.org/specification/v0_9/standard_catalog.json",
55+
"theme": {
56+
"primaryColor": "#00BFFF",
57+
"customProperty": "customValue"
58+
}
59+
}
60+
}
61+
}
62+
]
63+
}

0 commit comments

Comments
 (0)