Skip to content

Commit 7e63caf

Browse files
gspencergoogholtskinner
gspencergoog
and
holtskinner
authored
docs: Update protocol docs and schema files (#27)
* Update protocol docs * Add dynamicCatalog description, update old proposal formatting * Remove style from dynamic catalog * Add valueList to data model * Clean up schema files * Fix JSON fragment --------- Co-authored-by: Holt Skinner <[email protected]>
1 parent 6becbce commit 7e63caf

File tree

10 files changed

+1062
-1940
lines changed

10 files changed

+1062
-1940
lines changed

‎README.md‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
1-
# A2UI (Generative UI Language Format) Protocol
1+
# A2UI (Agent to UI) Protocol
22

3-
This repository contains the specification for the A2UI (Generative UI Language Format) protocol, a JSONL-based, streaming UI protocol designed to be easily generated by Large Language Models (LLMs).
3+
This repository contains the specification for the A2UI protocol, a JSONL-based, streaming UI protocol designed to be easily generated by Large Language Models (LLMs).
44

55
## Project Overview
66

77
The A2UI protocol enables a server to stream a platform-agnostic, abstract UI definition to a client, which then renders it progressively using a native widget set. The core design principles are:
88

9-
* **LLM-Friendly**: The protocol uses a simple, declarative, and flat structure that is easy for LLMs to generate.
10-
* **Progressive Rendering**: The UI is streamed as a series of JSONL messages, allowing the client to render the UI as it arrives, improving perceived performance.
11-
* **Platform-Agnostic**: The protocol defines an abstract component tree, and the client is responsible for mapping these abstract components to its native widget implementations.
12-
* **Separation of Concerns**: The protocol separates the UI structure (components), the application state (data model), and the client-side widget rendering.
9+
- **LLM-Friendly**: The protocol uses a simple, declarative, and flat structure that is easy for LLMs to generate.
10+
- **Progressive Rendering**: The UI is streamed as a series of JSONL messages, allowing the client to render the UI as it arrives, improving perceived performance.
11+
- **Platform-Agnostic**: The protocol defines an abstract component tree, and the client is responsible for mapping these abstract components to its native widget implementations.
12+
- **Separation of Concerns**: The protocol separates the UI structure (components), the application state (data model), and the client-side widget rendering.
1313

1414
## Repository Layout
1515

1616
The repository is structured as follows:
1717

18-
* `docs/`: This directory contains the formal specification for the A2UI protocol (`docs/a2ui_protocol.md`) and related design documents and proposals.
19-
* `specification/json/`: This directory contains the JSON schema files used to validate A2UI protocol messages and client event messages.
18+
- `docs/`: This directory contains the formal specification for the A2UI protocol (`docs/a2ui_protocol.md`) and related design documents and proposals.
19+
- `specification/json/`: This directory contains the JSON schema files used to validate A2UI protocol messages and client event messages.

‎docs/a2ui_protocol.md‎

Lines changed: 853 additions & 114 deletions
Large diffs are not rendered by default.

‎docs/proposals/v0_8.md‎

Lines changed: 95 additions & 115 deletions
Large diffs are not rendered by default.

‎specification/json/catalog_description_schema.json‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

‎specification/json/client_event_schema.json‎

Lines changed: 0 additions & 75 deletions
This file was deleted.

‎specification/json/client_to_server.json‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
{
2+
"title": "A2UI (Agent to UI) Client-to-Server Event Schema",
3+
"description": "Describes a JSON payload for a client-to-server event message.",
4+
"type": "object",
5+
"minProperties": 1,
6+
"maxProperties": 1,
7+
"properties": {
8+
"userAction": {
9+
"type": "object",
10+
"description": "Reports a user-initiated action from a component.",
11+
"properties": {
12+
"name": {
13+
"type": "string",
14+
"description": "The name of the action, taken from the component's action.name property."
15+
},
16+
"surfaceId": {
17+
"type": "string",
18+
"description": "The id of the surface where the event originated."
19+
},
20+
"sourceComponentId": {
21+
"type": "string",
22+
"description": "The id of the component that triggered the event."
23+
},
24+
"timestamp": {
25+
"type": "string",
26+
"format": "date-time",
27+
"description": "An ISO 8601 timestamp of when the event occurred."
28+
},
29+
"context": {
30+
"type": "object",
31+
"description": "A JSON object containing the key-value pairs from the component's action.context, after resolving all data bindings.",
32+
"additionalProperties": true
33+
}
34+
},
35+
"required": [
36+
"name",
37+
"surfaceId",
38+
"sourceComponentId",
39+
"timestamp",
40+
"context"
41+
]
42+
},
43+
"clientUiCapabilities": {
44+
"type": "object",
45+
"description": "Informs the server about the client's capabilities, such as the component catalog it supports. Exactly ONE of the properties in this object must be set.",
46+
"properties": {
47+
"catalogUri": {
48+
"type": "string",
49+
"format": "uri",
50+
"description": "A URI pointing to a predefined component catalog schema that the server advertized, and the client supports."
51+
},
52+
"dynamicCatalog": {
53+
"type": "object",
54+
"description": "An inline JSON object that defines the client's supported components.",
55+
"properties": {
56+
"components": {
57+
"type": "object",
58+
"description": "A map where each key is a component name and the value is a JSON Schema defining an object containing its properties.",
59+
"additionalProperties": {
60+
"$ref": "https://json-schema.org/draft/2020-12/schema"
61+
}
62+
}
63+
},
64+
"required": ["components"]
65+
}
66+
},
67+
"oneOf": [
68+
{ "required": ["catalogUri"] },
69+
{ "required": ["dynamicCatalog"] }
70+
]
71+
},
72+
"error": {
73+
"type": "object",
74+
"description": "Reports a client-side error. The content is flexible.",
75+
"additionalProperties": true
76+
}
77+
},
78+
"oneOf": [
79+
{ "required": ["userAction"] },
80+
{ "required": ["clientUiCapabilities"] },
81+
{ "required": ["error"] }
82+
]
83+
}

‎specification/json/protocol_schema.json‎

Lines changed: 0 additions & 87 deletions
This file was deleted.

specification/json/protocol_schema_llm.json renamed to specification/json/server_to_client.json

Lines changed: 23 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"title": "A2UI Message Schema",
3-
"description": "Describes a JSON payload for an A2UI message, which is used to dynamically construct and update user interfaces. A message MUST contain exactly ONE of the action properties: 'beginRendering', 'surfaceUpdate', 'dataModelUpdate', or 'surfaceDeletion'.",
3+
"description": "Describes a JSON payload for an A2UI (Agent to UI) message, which is used to dynamically construct and update user interfaces. A message MUST contain exactly ONE of the action properties: 'beginRendering', 'surfaceUpdate', 'dataModelUpdate', or 'deleteSurface'.",
44
"type": "object",
55
"properties": {
66
"beginRendering": {
@@ -23,10 +23,6 @@
2323
"type": "string",
2424
"description": "The primary font for the UI."
2525
},
26-
"logoUrl": {
27-
"type": "string",
28-
"description": "A URL for the logo image."
29-
},
3026
"primaryColor": {
3127
"type": "string",
3228
"description": "The primary UI color as a hexadecimal code (e.g., '#00BFFF').",
@@ -639,26 +635,39 @@
639635
"description": "An array of data entries. Each entry must contain a 'key' and exactly one corresponding typed 'value*' property.",
640636
"items": {
641637
"type": "object",
642-
"description": "A single data entry. Exactly one 'value_' property should be provided alongside the key.",
638+
"description": "A single data entry. Exactly one 'value*' property should be provided alongside the key.",
643639
"properties": {
644640
"key": {
645641
"type": "string",
646642
"description": "The key for this data entry."
647643
},
648644
"valueString": {
649-
"type": "string",
650-
"description": "A string value."
645+
"type": "string"
651646
},
652647
"valueNumber": {
653-
"type": "number",
654-
"description": "A number value."
648+
"type": "number"
655649
},
656650
"valueBoolean": {
657-
"type": "boolean",
658-
"description": "A boolean value."
651+
"type": "boolean"
652+
},
653+
"valueList": {
654+
"type": "array",
655+
"items": {
656+
"type": "object",
657+
"properties": {
658+
"valueString": {
659+
"type": "string"
660+
},
661+
"valueNumber": {
662+
"type": "number"
663+
},
664+
"valueBoolean": {
665+
"type": "boolean"
666+
}
667+
}
668+
}
659669
}
660-
},
661-
"required": ["key"]
670+
}
662671
}
663672
}
664673
},

0 commit comments

Comments
 (0)