docs: Update protocol docs and schema files

README.md

@@ -1,19 +1,19 @@
-# A2UI (Generative UI Language Format) Protocol
+# A2UI (Agent to UI) Protocol
 
-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).
+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).
 
 ## Project Overview
 
 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:
 
-*   **LLM-Friendly**: The protocol uses a simple, declarative, and flat structure that is easy for LLMs to generate.
-*   **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.
-*   **Platform-Agnostic**: The protocol defines an abstract component tree, and the client is responsible for mapping these abstract components to its native widget implementations.
-*   **Separation of Concerns**: The protocol separates the UI structure (components), the application state (data model), and the client-side widget rendering.
+- **LLM-Friendly**: The protocol uses a simple, declarative, and flat structure that is easy for LLMs to generate.
+- **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.
+- **Platform-Agnostic**: The protocol defines an abstract component tree, and the client is responsible for mapping these abstract components to its native widget implementations.
+- **Separation of Concerns**: The protocol separates the UI structure (components), the application state (data model), and the client-side widget rendering.
 
 ## Repository Layout
 
 The repository is structured as follows:
 
-*   `docs/`: This directory contains the formal specification for the A2UI protocol (`docs/a2ui_protocol.md`) and related design documents and proposals.
-*   `specification/json/`: This directory contains the JSON schema files used to validate A2UI protocol messages and client event messages.
+- `docs/`: This directory contains the formal specification for the A2UI protocol (`docs/a2ui_protocol.md`) and related design documents and proposals.
+- `specification/json/`: This directory contains the JSON schema files used to validate A2UI protocol messages and client event messages.

specification/json/client_to_server.json

@@ -0,0 +1,83 @@
+{
+  "title": "A2UI (Agent to UI) Client-to-Server Event Schema",
+  "description": "Describes a JSON payload for a client-to-server event message.",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 1,
+  "properties": {
+    "userAction": {
+      "type": "object",
+      "description": "Reports a user-initiated action from a component.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the action, taken from the component's action.name property."
+        },
+        "surfaceId": {
+          "type": "string",
+          "description": "The id of the surface where the event originated."
+        },
+        "sourceComponentId": {
+          "type": "string",
+          "description": "The id of the component that triggered the event."
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "An ISO 8601 timestamp of when the event occurred."
+        },
+        "context": {
+          "type": "object",
+          "description": "A JSON object containing the key-value pairs from the component's action.context, after resolving all data bindings.",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "name",
+        "surfaceId",
+        "sourceComponentId",
+        "timestamp",
+        "context"
+      ]
+    },
+    "clientUiCapabilities": {
+      "type": "object",
+      "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.",
+      "properties": {
+        "catalogUri": {
+          "type": "string",
+          "format": "uri",
+          "description": "A URI pointing to a predefined component catalog schema that the server advertized, and the client supports."
+        },
+        "dynamicCatalog": {
+          "type": "object",
+          "description": "An inline JSON object that defines the client's supported components.",
+          "properties": {
+            "components": {
+              "type": "object",
+              "description": "A map where each key is a component name and the value is a JSON Schema defining an object containing its properties.",
+              "additionalProperties": {
+                "$ref": "https://json-schema.org/draft/2020-12/schema"
+              }
+            }
+          },
+          "required": ["components"]
+        }
+      },
+      "oneOf": [
+        { "required": ["catalogUri"] },
+        { "required": ["dynamicCatalog"] }
+      ]
+    },
+    "error": {
+      "type": "object",
+      "description": "Reports a client-side error. The content is flexible.",
+      "additionalProperties": true
+    }
+  },
+  "oneOf": [
+    { "required": ["userAction"] },
+    { "required": ["clientUiCapabilities"] },
+    { "required": ["error"] }
+  ]
+}

specification/json/protocol_schema_llm.json → specification/json/server_to_client.json

@@ -1,6 +1,6 @@
 {
   "title": "A2UI Message Schema",
-  "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'.",
+  "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'.",
   "type": "object",
   "properties": {
     "beginRendering": {
@@ -23,10 +23,6 @@
               "type": "string",
               "description": "The primary font for the UI."
             },
-            "logoUrl": {
-              "type": "string",
-              "description": "A URL for the logo image."
-            },
             "primaryColor": {
               "type": "string",
               "description": "The primary UI color as a hexadecimal code (e.g., '#00BFFF').",
@@ -639,26 +635,39 @@
           "description": "An array of data entries. Each entry must contain a 'key' and exactly one corresponding typed 'value*' property.",
           "items": {
             "type": "object",
-            "description": "A single data entry. Exactly one 'value_' property should be provided alongside the key.",
+            "description": "A single data entry. Exactly one 'value*' property should be provided alongside the key.",
             "properties": {
               "key": {
                 "type": "string",
                 "description": "The key for this data entry."
               },
               "valueString": {
-                "type": "string",
-                "description": "A string value."
+                "type": "string"
               },
               "valueNumber": {
-                "type": "number",
-                "description": "A number value."
+                "type": "number"
               },
               "valueBoolean": {
-                "type": "boolean",
-                "description": "A boolean value."
+                "type": "boolean"
+              },
+              "valueList": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "valueString": {
+                      "type": "string"
+                    },
+                    "valueNumber": {
+                      "type": "number"
+                    },
+                    "valueBoolean": {
+                      "type": "boolean"
+                    }
+                  }
+                }
               }
-            },
-            "required": ["key"]
+            }
           }
         }
       },