Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/concepts/catalogs.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ This guide defines the A2UI Catalog architecture and provides a roadmap for impl

## Catalog Definition

A catalog is a [JSON Schema file](../specification/v0_9/json/a2ui_client_capabilities.json#L62C5-L95C6) outlining the components, functions, and themes that agents can use to define A2UI surfaces using server-driven UI. All A2UI JSON sent from the agent is validated against the chosen catalog.
A catalog is a [JSON Schema file](../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) outlining the components, functions, and themes that agents can use to define A2UI surfaces using server-driven UI. All A2UI JSON sent from the agent is validated against the chosen catalog.

[Catalog JSON Schema](../specification/v0_9/json/a2ui_client_capabilities.json#L62C5-L95C6) is below
[Catalog JSON Schema](../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) is below

```json
{
Expand Down Expand Up @@ -81,14 +81,14 @@ For simplicity we recommend building catalogs that directly reflect a client's d

### Recommendations

| Usecase | Recommendation | Effort |
| :--- | :--- | :--- |
| Adding A2UI to a mature frontend | Define a catalog that mirrors your existing design system. | Medium |
| Usecase | Recommendation | Effort |
| :---------------------------------- | :----------------------------------------------------------------------------- | :----------------------------- |
| Adding A2UI to a mature frontend | Define a catalog that mirrors your existing design system. | Medium |
| Adding A2UI to a new/greenfield app | Start with Basic Catalog, then evolve into your own catalog as the app evolves | Low (assuming renderer exists) |

## Building a Catalog

A catalog is a JSON Schema file that conforms to the [Catalog schema](../specification/v0_9/json/a2ui_client_capabilities.json#L62C5-L95C6) that defines the components, themes and functions an agent can use when building a surface.
A catalog is a JSON Schema file that conforms to the [Catalog schema](../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) that defines the components, themes and functions an agent can use when building a surface.

### Example: A Minimal Catalog

Expand Down Expand Up @@ -365,9 +365,9 @@ We recommend including the version in the catalogId. This allows using A2UI cata

**Recommended Pattern:**

| Change Type | URI Example | Description |
| :--- | :--- | :--- |
| **Current** | .../rizzcharts/v1/catalog.json | The stable, production schema. |
| Change Type | URI Example | Description |
| :----------- | :----------------------------- | :----------------------------------------------------------------- |
| **Current** | .../rizzcharts/v1/catalog.json | The stable, production schema. |
| **Breaking** | .../rizzcharts/v2/catalog.json | A new schema introducing renamed components or structural changes. |

### Handling Migrations
Expand Down
10 changes: 5 additions & 5 deletions specification/v0_10/docs/a2ui_protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -568,7 +568,7 @@ _Replace the entire data model:_

### Client to server updates

When `sendDataModel` is set to `true` for a surface, the client automatically appends the **entire data model** of that surface to the metadata of every message (such as `action` or user query) sent to the server that created the surface. The data model is included using the transport's metadata facility (e.g., the `metadata` field in A2A or a header in HTTP). The payload follows the schema in [`a2ui_client_data_model.json`](../json/a2ui_client_data_model.json).
When `sendDataModel` is set to `true` for a surface, the client automatically appends the **entire data model** of that surface to the metadata of every message (such as `action` or user query) sent to the server that created the surface. The data model is included using the transport's metadata facility (e.g., the `metadata` field in A2A or a header in HTTP). The payload follows the schema in [`client_data_model.json`](../json/client_data_model.json).

- **Targeted Delivery**: The data model is sent exclusively to the server that created the surface. Data cannot leak to other agents or servers.
- **Trigger:** Data is sent only when a client-to-server message is triggered (e.g., by a user action like a button click). Passive data changes (like typing in a text field) do not trigger a network request on their own; they simply update the local state, which will be sent with the next action.
Expand Down Expand Up @@ -824,7 +824,7 @@ A server (or agent) advertises its capabilities using the [`server_capabilities.

#### Client capabilities

The `a2uiClientCapabilities` object in the metadata follows the [`a2ui_client_capabilities.json`] schema.
The `a2uiClientCapabilities` object in the metadata follows the [`client_capabilities.json`] schema.

**Properties:**

Expand All @@ -833,7 +833,7 @@ The `a2uiClientCapabilities` object in the metadata follows the [`a2ui_client_ca

#### Client data model

When `sendDataModel` is enabled for a surface, the client includes the `a2uiClientDataModel` object in the metadata, following the [`a2ui_client_data_model.json`] schema.
When `sendDataModel` is enabled for a surface, the client includes the `a2uiClientDataModel` object in the metadata, following the [`client_data_model.json`] schema.

**Properties:**

Expand All @@ -848,7 +848,7 @@ This message is used to report a client-side error to the server.
[`server_to_client.json`]: ../json/server_to_client.json
[`client_to_server.json`]: ../json/client_to_server.json
[`server_capabilities.json`]: ../json/server_capabilities.json
[`a2ui_client_capabilities.json`]: ../json/a2ui_client_capabilities.json
[`a2ui_client_data_model.json`]: ../json/a2ui_client_data_model.json
[`client_capabilities.json`]: ../json/client_capabilities.json
[`client_data_model.json`]: ../json/client_data_model.json
[JSON Pointer]: https://datatracker.ietf.org/doc/html/rfc6901
[RFC 6901]: https://datatracker.ietf.org/doc/html/rfc6901
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://a2ui.org/specification/v0_10/a2ui_client_capabilities.json",
"$id": "https://a2ui.org/specification/v0_10/client_capabilities.json",
"title": "A2UI Client Capabilities Schema",
"description": "A schema for the a2uiClientCapabilities object, which is sent from the client to the server as part of the A2A metadata to describe the client's UI rendering capabilities.",
"type": "object",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://a2ui.org/specification/v0_10/a2ui_client_data_model.json",
"$id": "https://a2ui.org/specification/v0_10/client_data_model.json",
"title": "A2UI Client Data Model Schema",
"description": "Schema for attaching the client data model to A2A message metadata. This object should be placed in the `a2uiClientDataModel` field of the metadata.",
"type": "object",
Expand Down
10 changes: 5 additions & 5 deletions specification/v0_9/docs/a2ui_protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -574,7 +574,7 @@ _Replace the entire data model:_

### Client to server updates

When `sendDataModel` is set to `true` for a surface, the client automatically appends the **entire data model** of that surface to the metadata of every message (such as `action` or user query) sent to the server that created the surface. The data model is included using the transport's metadata facility (e.g., the `metadata` field in A2A or a header in HTTP). The payload follows the schema in [`a2ui_client_data_model.json`](../json/a2ui_client_data_model.json).
When `sendDataModel` is set to `true` for a surface, the client automatically appends the **entire data model** of that surface to the metadata of every message (such as `action` or user query) sent to the server that created the surface. The data model is included using the transport's metadata facility (e.g., the `metadata` field in A2A or a header in HTTP). The payload follows the schema in [`client_data_model.json`](../json/client_data_model.json).

- **Targeted Delivery**: The data model is sent exclusively to the server that created the surface. Data cannot leak to other agents or servers.
- **Trigger:** Data is sent only when a client-to-server message is triggered (e.g., by a user action like a button click). Passive data changes (like typing in a text field) do not trigger a network request on their own; they simply update the local state, which will be sent with the next action.
Expand Down Expand Up @@ -830,7 +830,7 @@ A server (or agent) advertises its capabilities using the [`server_capabilities.

#### Client capabilities

The `a2uiClientCapabilities` object in the metadata follows the [`a2ui_client_capabilities.json`] schema.
The `a2uiClientCapabilities` object in the metadata follows the [`client_capabilities.json`] schema.

**Properties:**

Expand All @@ -839,7 +839,7 @@ The `a2uiClientCapabilities` object in the metadata follows the [`a2ui_client_ca

#### Client data model

When `sendDataModel` is enabled for a surface, the client includes the `a2uiClientDataModel` object in the metadata, following the [`a2ui_client_data_model.json`] schema.
When `sendDataModel` is enabled for a surface, the client includes the `a2uiClientDataModel` object in the metadata, following the [`client_data_model.json`] schema.

**Properties:**

Expand All @@ -854,7 +854,7 @@ This message is used to report a client-side error to the server.
[`server_to_client.json`]: ../json/server_to_client.json
[`client_to_server.json`]: ../json/client_to_server.json
[`server_capabilities.json`]: ../json/server_capabilities.json
[`a2ui_client_capabilities.json`]: ../json/a2ui_client_capabilities.json
[`a2ui_client_data_model.json`]: ../json/a2ui_client_data_model.json
[`client_capabilities.json`]: ../json/client_capabilities.json
[`client_data_model.json`]: ../json/client_data_model.json
[JSON Pointer]: https://datatracker.ietf.org/doc/html/rfc6901
[RFC 6901]: https://datatracker.ietf.org/doc/html/rfc6901
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://a2ui.org/specification/v0_9/a2ui_client_capabilities.json",
"$id": "https://a2ui.org/specification/v0_9/client_capabilities.json",
"title": "A2UI Client Capabilities Schema",
"description": "A schema for the a2uiClientCapabilities object, which is sent from the client to the server as part of the A2A metadata to describe the client's UI rendering capabilities.",
"type": "object",
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://a2ui.org/specification/v0_9/a2ui_client_data_model.json",
"$id": "https://a2ui.org/specification/v0_9/client_data_model.json",
"title": "A2UI Client Data Model Schema",
"description": "Schema for attaching the client data model to A2A message metadata. This object should be placed in the `a2uiClientDataModel` field of the metadata.",
"type": "object",
Expand Down
Loading