diff --git a/docs/concepts/catalogs.md b/docs/concepts/catalogs.md index c4b471111..b5f46fa55 100644 --- a/docs/concepts/catalogs.md +++ b/docs/concepts/catalogs.md @@ -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 { @@ -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 @@ -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 diff --git a/specification/v0_10/docs/a2ui_protocol.md b/specification/v0_10/docs/a2ui_protocol.md index 65f7dad4a..d8bcf2701 100644 --- a/specification/v0_10/docs/a2ui_protocol.md +++ b/specification/v0_10/docs/a2ui_protocol.md @@ -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. @@ -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:** @@ -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:** @@ -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 diff --git a/specification/v0_10/json/a2ui_client_capabilities.json b/specification/v0_10/json/client_capabilities.json similarity index 97% rename from specification/v0_10/json/a2ui_client_capabilities.json rename to specification/v0_10/json/client_capabilities.json index 13590e9d5..c5122d2aa 100644 --- a/specification/v0_10/json/a2ui_client_capabilities.json +++ b/specification/v0_10/json/client_capabilities.json @@ -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", diff --git a/specification/v0_10/json/a2ui_client_data_model.json b/specification/v0_10/json/client_data_model.json similarity index 90% rename from specification/v0_10/json/a2ui_client_data_model.json rename to specification/v0_10/json/client_data_model.json index 957153fe3..8534f361c 100644 --- a/specification/v0_10/json/a2ui_client_data_model.json +++ b/specification/v0_10/json/client_data_model.json @@ -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", diff --git a/specification/v0_9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md index 0f469659b..0caf57d60 100644 --- a/specification/v0_9/docs/a2ui_protocol.md +++ b/specification/v0_9/docs/a2ui_protocol.md @@ -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. @@ -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:** @@ -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:** @@ -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 diff --git a/specification/v0_9/json/a2ui_client_capabilities.json b/specification/v0_9/json/client_capabilities.json similarity index 97% rename from specification/v0_9/json/a2ui_client_capabilities.json rename to specification/v0_9/json/client_capabilities.json index 77bd6027c..e417252bf 100644 --- a/specification/v0_9/json/a2ui_client_capabilities.json +++ b/specification/v0_9/json/client_capabilities.json @@ -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", diff --git a/specification/v0_9/json/a2ui_client_data_model.json b/specification/v0_9/json/client_data_model.json similarity index 90% rename from specification/v0_9/json/a2ui_client_data_model.json rename to specification/v0_9/json/client_data_model.json index 7d9a7dbb8..3757f0c6a 100644 --- a/specification/v0_9/json/a2ui_client_data_model.json +++ b/specification/v0_9/json/client_data_model.json @@ -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",