Update v0.8 spec with updated catalog negotiation style

specification/0.8/docs/a2ui_extension_specification.md

@@ -12,7 +12,7 @@ This is the only URI accepted for this extension.
 
 ## Core Concepts
 
-The A2UI extension is built on three main concepts:
+The A2UI extension is built on the following main concepts:
 
 Surfaces: A "Surface" is a distinct, controllable region of the client's UI. The spec uses a surfaceId to direct updates to specific surfaces (e.g., a main content area, a side panel, or a new chat bubble). This allows a single agent stream to manage multiple UI areas independently.
 
@@ -24,28 +24,31 @@ Catalog Definition Schema: A standard format for defining a library of component
 
 Server-to-Client Message Schema: The core wire format for messages sent from the agent to the client (e.g., surfaceUpdate, dataModelUpdate).
 
-Client-to-Server Event Schema: The core wire format for messages sent from the client to the agent (e.g., userAction, clientUiCapabilities).
+Client-to-Server Event Schema: The core wire format for messages sent from the client to the agent (e.g., userAction).
 
-Agent Capability Declaration
-Agents advertise their A2UI capabilities in their AgentCard within the AgentCapabilities.extensions list. The params object defines the agent's specific UI support, including which component catalogs it can generate and whether it accepts dynamic catalogs from the client.
+Client Capabilities: The client sends its capabilities to the server in an `a2uiClientCapabilities` object. This object is included in the `metadata` field of every A2A `Message` sent from the client to the server.This object allows the client to declare which catalogs it supports.
 
-Example AgentExtension block:
-
-Parameter Definitions
-params.supportedSchemas: (REQUIRED) An array of strings, where each string is a URI pointing to a component Catalog Definition Schema that the agent can generate. This could include the default catalog or custom catalogs or both.
-
-params.acceptsDynamicSchemas: (OPTIONAL) A boolean indicating if the agent can accept a clientUiCapabilities message containing a dynamicCatalog. If omitted, this defaults to false.
+## Agent Card details
 
-Client Capability Declaration
-The client-to-server spec includes a clientUiCapabilities message. If a client wishes to use a specific catalog (other than the server's default) or provide its own dynamic catalog, it MUST send this message after the connection is established and before the first user prompt.
+Agents advertise their A2UI capabilities in their AgentCard within the `AgentCapabilities.extensions` list. The `params` object defines the agent's specific UI support.
 
-This message allows the client to specify either:
-
-A catalogUri: A URI for a known, shared catalog (which must be one of the supportedSchemas from the agent).
-
-A dynamicCatalog: An inline Catalog Definition Schema object. This is only allowed if the agent's acceptsDynamicSchemas capability is true.
+Example AgentExtension block:
 
-Extension Activation
+```json
+{
+  "uri": "https://a2ui.org/ext/a2a-ui/v0.8",
+  "description": "Ability to render A2UI",
+  "required": false,
+  "params": {
+    "acceptsInlineCatalogs": true
+  }
+}
+```
+
+### Parameter Definitions
+- `params.acceptsInlineCatalogs`: (OPTIONAL) A boolean indicating if the agent can accept an `inlineCatalogs` array in the client's `a2uiClientCapabilities`. If omitted, this defaults to `false`.
+
+## Extension Activation
 Clients indicate their desire to use the A2UI extension by specifying it via the transport-defined A2A extension activation mechanism.
 
 For JSON-RPC and HTTP transports, this is indicated via the X-A2A-Extensions HTTP header.

specification/0.8/docs/a2ui_protocol.md

@@ -62,13 +62,12 @@ Communication occurs via a JSON Lines (JSONL) stream. The client parses each lin
 
 - `surfaceUpdate`: Provides a list of component definitions to be added to or updated in a specific UI area called a "surface."
 - `dataModelUpdate`: Provides new data to be inserted into or to replace a surface's data model. Each surface has its own data model.
-- `beginRendering`: Signals to the client that it has enough information to perform the initial render, specifying the ID of the root component.
+- `beginRendering`: Signals to the client that it has enough information to perform the initial render, specifying the ID of the root component and, optionally, the component catalog to use.
 - `deleteSurface`: Explicitly removes a surface and its contents from the UI.
 
-Client-to-server communication for user interactions is handled separately via a JSON payload sent to a REST API. This message can be one of several types:
+Client-to-server communication for user interactions is handled separately via an A2A message. This message can be one of two types:
 
 - `userAction`: Reports a user-initiated action from a component.
-- `clientUiCapabilities`: Informs the server about the client's capabilities, such as the component catalog it supports.
 - `error`: Reports a client-side error.
   This keeps the primary data stream unidirectional.
 
@@ -167,13 +166,105 @@ The following is a complete, minimal example of a JSONL stream that renders a us
 
 A2UI's component model is designed for flexibility, separating the protocol from the component set.
 
-### 2.1. The Catalog: Defining Components
+### 2.1. Catalog Negotiation
 
-Unlike previous versions with a fixed component set, A2UI now defines components in a **Catalog**. A catalog is a schema that defines the available component types (e.g., `Row`, `Text`) and their supported properties. This allows for different clients to support different sets of components, including custom ones. The server must generate `surfaceUpdate` messages that conform to the component catalog understood by the client. Clients can inform the server of the catalog they support using the `clientUiCapabilities` message.
+A **Catalog** defines the contract between the server and the client for the UI that can be rendered. It contains a list of supported component types (e.g., `Row`, `Text`), their properties, and available styles. A catalog is defined by a **Catalog Definition Document**.
+
+There is a **Standard Catalog** associated with each version of the A2UI protocol. For v0.8, its identifier is `a2ui.org:standard_catalog_0_8_0`.
+
+Catalog IDs are simple strings. While they can be anything, it's recommended to use an internet domain you own as a prefix (e.g., `my-company.com:my-custom-catalog`) to avoid collisions. Furthermore, if any changes are made to a catalog that could break compatibility between an agent and renderer, a new `catalogId` **must** be assigned. This ensures clear versioning and prevents unexpected behavior if an agent has changes but the client does not, or vice versa.
+
+The negotiation process allows the client and server to agree on which catalog to use for a given UI surface. This process is designed to be flexible, supporting standard, custom, and even dynamically-defined catalogs.
+
+The flow is as follows:
+
+#### 1. Server Advertises Capabilities
+
+The server (agent) advertises its capabilities in its Agent Card as part of the A2A protocol. For A2UI, this includes whether it can handle catalogs defined inline by the client.
+
+- `acceptsInlineCatalogs` (boolean, optional): If `true`, the server can process `inlineCatalogs` sent by the client. Defaults to `false`.
+
+**Example Server Agent Card Snippet:**
+```json
+{
+  "name": "Restaurant Finder",
+  "capabilities": {
+    "extensions": [
+      {
+        "uri": "https://a2ui.org/ext/a2a-ui/v0.8",
+        "params": {
+          "acceptsInlineCatalogs": true
+        }
+      }
+    ]
+  }
+}
+```
+
+#### 2. Client Declares Supported Catalogs
+
+In **every** message sent to the server, the client includes an `a2uiClientCapabilities` object within the A2A `Message` metadata. This object informs the server of all catalogs the client can render.
+
+- `supportedCatalogIds` (array of strings, required): A list of identifiers for all pre-defined catalogs the client supports. The client must explicitly include the standard catalog ID here if it supports the standard catalog.
+- `inlineCatalogs` (array of objects, optional): An array of full Catalog Definition Documents. This allows a client to provide custom, on-the-fly catalogs. This may only be provided if the server has advertised `acceptsInlineCatalogs: true`.
+
+**Example A2A Message with Client Capabilities:**
+```json
+{
+  "metadata": {
+    "a2uiClientCapabilities": {
+      "supportedCatalogIds": [
+        "a2ui.org:standard_catalog_0_8_0",
+        "my-company.com:custom-reporting-catalog-1.2"
+      ],
+      "inlineCatalogs": [
+        {
+          "catalogId": "my-company.com:temp-signature-pad-catalog",
+          "components": {
+            "SignaturePad": {
+              "type": "object",
+              "properties": { "penColor": { "type": "string" } }
+            }
+          },
+          "styles": {}
+        }
+      ]
+    }
+  },
+  "message": {
+    "prompt": {
+      "text": "Find me a good restaurant"
+    }
+  }
+}
+```
+
+#### 3. Server Chooses Catalog and Renders
+
+The server receives the client's capabilities and chooses a catalog to use for a specific UI surface. The server specifies its choice in the `beginRendering` message using the `catalogId` field.
+
+- `catalogId` (string, optional): The identifier of the chosen catalog. This ID must be one of the `supportedCatalogIds` or the `catalogId` from one of the `inlineCatalogs` provided by the client.
+
+If the `catalogId` is omitted, the client **MUST** default to the standard catalog for the protocol version (`a2ui.org:standard_catalog_0_8_0`).
+
+**Example `beginRendering` Message:**
+```json
+{
+  "beginRendering": {
+    "surfaceId": "unique-surface-1",
+    "catalogId": "my-company.com:custom-reporting-catalog-1.2",
+    "root": "root-component-id"
+  }
+}
+```
+Each surface can use a different catalog, providing a high degree of flexibility.
 
 #### Schemas for Developers
 
-When building an agent, it is recommended to use a resolved schema that includes the specific component catalog you are targeting (e.g., `server_to_client_with_standard_catalog.json`). This provides the LLM with a strict definition of all available components and their properties, leading to more reliable UI generation. The generic `server_to_client.json` is the abstract wire protocol, while the resolved schema is the concrete tool for generation.
+When building an agent, it is recommended to use a resolved schema that includes the specific component catalog you are targeting (e.g., a custom schema combining `server_to_client.json` with your `my-company.com:custom-reporting-catalog-1.2` definition). This provides the LLM with a strict definition of all available components and their properties, leading to more reliable UI generation. The generic `server_to_client.json` is the abstract wire protocol, while the resolved schema is the concrete tool for generation.
+
+See `server_to_client_with_standard_catalog.json` for an example of a resolved 
+schema which has the components substituted in.
 
 ### 2.2. The `surfaceUpdate` Message
 
@@ -414,7 +505,7 @@ While the server-to-client UI definition is a one-way stream (e.g., over SSE), u
 
 ### 5.1. The Client Event Message
 
-The client sends a single JSON object that acts as a wrapper. It must contain exactly one of the following keys: `userAction`, `clientUiCapabilities`, or `error`.
+The client sends a single JSON object that acts as a wrapper. It must contain exactly one of the following keys: `userAction` or `error`.
 
 ### 5.2. The `userAction` Message
 
@@ -430,60 +521,11 @@ The `userAction` object has the following structure:
 
 The process for resolving the `action.context` remains the same: the client iterates over the `context` array, resolves all literal or data-bound values, and constructs the `context` object.
 
-### 5.3. The `clientUiCapabilities` Message
-
-This message is sent by the client to inform the server about its capabilities. This is crucial for supporting different component sets, allowing the server to generate UI that is compatible with the client. The message must contain exactly one of the following properties: `catalogUri` or `dynamicCatalog`.
-
-- `catalogUri`: A URI pointing to a predefined component catalog schema that the client supports.
-- `dynamicCatalog`: An inline JSON object, conforming to the Catalog Schema, that defines the client's supported components. This is useful for development or for clients with highly custom component sets.
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant Server
-    Client->>+Server: POST /event (clientUiCapabilities with catalog)
-    Server-->>-Client: HTTP 200 OK
-    Note over Server: Server now knows which catalog to use.
-    Server->>+Client: SSE Connection (JSONL Stream using client's catalog)
-    Client-->>-Server: (Renders UI based on custom/specified catalog)
-```
-
-#### `dynamicCatalog`
-
-The `dynamicCatalog` property allows the client to send an inline JSON object that defines its entire supported component set. This is especially useful for development or for clients with highly custom components. The object must conform to the Catalog Schema, containing `components`.
-
-- `components`: An object where each key is the name of a component (e.g., `"MyCustomCard"`) and the value is a valid JSON object schema defining the properties for that component.
-
-**Example of a `clientUiCapabilities` message:**
-
-```json
-{
-  "clientUiCapabilities": {
-    "dynamicCatalog": {
-      "components": {
-        "MyCustomCard": {
-          "type": "object",
-          "properties": {
-            "title": {
-              "type": "string"
-            },
-            "child": {
-              "type": "string"
-            }
-          },
-          "required": ["title", "child"]
-        }
-      }
-    }
-  }
-}
-```
-
-### 5.4. The `error` Message
+### 5.3. The `error` Message
 
 This message provides a feedback mechanism for the server. It is sent when the client encounters an error, for instance, during UI rendering or data binding. The content of the object is flexible and can contain any relevant error information.
 
-### 5.5. Event Flow Example (`userAction`)
+### 5.4. Event Flow Example (`userAction`)
 
 1.  **Component Definition** (from `surfaceUpdate`):
 

specification/0.8/docs/custom_catalog_changes.md

@@ -0,0 +1,58 @@
+# Summary of Custom Catalog Negotiation Changes in A2UI v0.8
+
+This document summarizes the changes made to the A2UI protocol in v0.8 to support a more flexible and powerful custom catalog negotiation mechanism. It is intended as a guide for developers implementing these changes in agent or renderer libraries.
+
+The previous mechanism, which involved a single, one-time `clientUiCapabilities` message, has been deprecated. The new approach allows for a more dynamic, per-request declaration of capabilities, enabling a single client to support multiple catalogs and allowing the agent to choose the most appropriate one for each UI surface.
+
+## Key Changes to the Protocol
+
+1.  **Agent Capability Advertisement (`acceptsInlineCatalogs`)**: The agent's role in negotiation has been simplified. It now only declares whether it is capable of processing catalogs defined "inline" by the client.
+    *   **Relevant Doc**: [`a2ui_extension_specification.md`](./a2ui_extension_specification.md)
+
+2.  **Client Capabilities via A2A Metadata**: The client now sends its capabilities in an `a2uiClientCapabilities` object. Crucially, this is no longer a standalone message but is included in the `metadata` field of **every** A2A message sent to the agent.
+    *   This object contains `supportedCatalogIds` (an array of known catalog IDs) and an optional `inlineCatalogs` (an array of full catalog definitions).
+    *   **Relevant Doc**: The new process is explained in the [`a2ui_protocol.md`](./a2ui_protocol.md#catalog-negotiation) section on Catalog Negotiation.
+    *   **Relevant Schema**: [`a2ui_client_capabilities_schema.json`](../json/a2ui_client_capabilities_schema.json)
+
+3.  **Per-Surface Catalog Selection (`beginRendering`)**: The agent is now responsible for selecting which catalog to use for each UI surface. It signals its choice using the new optional `catalogId` field in the `beginRendering` message. If this field is omitted, the client must default to the Standard Catalog.
+    *   **Relevant Doc**: [`a2ui_protocol.md`](./a2ui_protocol.md#catalog-negotiation)
+    *   **Relevant Schema**: The change is reflected in [`server_to_client.json`](../json/server_to_client.json).
+
+4.  **Catalog Definition ID (`catalogId`)**: To facilitate identification, the catalog definition schema itself now has a required `catalogId` field.
+    *   **Relevant Schema**: [`catalog_description_schema.json`](../json/catalog_description_schema.json)
+
+---
+
+## Implementation Guide for Developers
+
+### For Agent (Server) Library Developers
+
+Your responsibilities are to process the client's declared capabilities and make a rendering choice.
+
+1.  **Advertise Capability**: In the agent's capability card, add the `acceptsInlineCatalogs: true` parameter within the A2UI extension block if you intend to support catalogs sent dynamically from the client.
+
+2.  **Parse Client Capabilities**: On every incoming A2A message, your library must parse the `metadata.a2uiClientCapabilities` object to determine which catalogs the client supports. You will get a list of `supportedCatalogIds` and potentially a list of `inlineCatalogs`.
+
+3.  **Choose a Catalog**: Before rendering a UI, decide which catalog to use. Your choice must be one of the catalogs advertised by the client in the capabilities object.
+
+4.  **Specify Catalog on Render**: When sending the `beginRendering` message for a surface, set the `catalogId` field to the ID of your chosen catalog (e.g., `"my-company.com:custom-catalog-1.2"`). If you do not set this field, you are implicitly requesting the use of the standard catalog.
+
+5.  **Generate Compliant UI**: Ensure that all components generated in subsequent `surfaceUpdate` messages for that surface conform to the properties and types defined in the chosen catalog.
+
+### For Renderer (Client) Library Developers
+
+Your responsibilities are to accurately declare your capabilities and render surfaces using the catalog selected by the agent.
+
+1.  **Declare Capabilities on Every Request**: For every A2A message your application sends, your library must inject the `a2uiClientCapabilities` object into the top-level `metadata` field.
+
+2.  **Populate `supportedCatalogIds`**: In the capabilities object, populate this array with the string identifiers of all pre-compiled catalogs your renderer supports. If your renderer supports the standard catalog for v0.8, you **should** include its ID: `a2ui.org:standard_catalog_0_8_0`.
+
+3.  **Provide `inlineCatalogs` (Optional)**: If your renderer supports dynamically generating or defining catalogs at runtime, include their full, valid Catalog Definition Documents in the `inlineCatalogs` array.
+
+4.  **Process `beginRendering`**: When your renderer receives a `beginRendering` message, it must inspect the new `catalogId` field.
+
+5.  **Select Catalog for Surface**:
+    *   If `catalogId` is present, use the corresponding catalog to render that surface. Your renderer must be able to look up the catalog from its pre-compiled list or from the inline definitions it just sent.
+    *   If `catalogId` is **absent**, you **must** default to using the Standard Catalog for v0.8 for that surface.
+
+6.  **Manage Multiple Catalogs**: Your renderer must be architected to handle multiple surfaces being rendered with different catalogs simultaneously. A dictionary mapping `surfaceId` to the chosen `catalog` is a common approach.