diff --git a/.gemini/GEMINI.md b/.gemini/GEMINI.md index 06d0faf3..e7e6f898 100644 --- a/.gemini/GEMINI.md +++ b/.gemini/GEMINI.md @@ -6,9 +6,9 @@ This document serves as a guide for using the Gemini agent within the A2UI repos The A2UI repository is organized into several key directories: -- `specification/0.8/docs/`: Contains the primary human-readable documentation for the A2UI protocol. +- `specification/v0_8/docs/`: Contains the primary human-readable documentation for the A2UI protocol. - `a2ui_protocol.md`: The foundational specification document. This is the best place to start to understand the protocol's fundamental goals. -- `specification/0.8/json/`: Contains the formal JSON schema definitions for the protocol. +- `specification/v0_8/json/`: Contains the formal JSON schema definitions for the protocol. - `server_to_client.json`: Defines the schema for messages sent from the server to the client. - `client_to_server.json`: Defines the schema for event messages sent from the client to the server. - `a2a_agents/python/`: Contains Python code relating to server-side integration of A2UI @@ -34,9 +34,9 @@ This document covers the design philosophy, architecture, data flow, and core co The formal, machine-readable definitions of the protocol are maintained as JSON schemas: -- **Server-to-Client Schema**: `@specification/0.8/json/server_to_client.json` -- **Server-to-Client Schema, with standard catalog**: `@specification/0.8/json/server_to_client_with_standard_catalog.json` -- **Client-to-Server Schema**: `@specification/0.8/json/client_to_server.json` +- **Server-to-Client Schema**: `@specification/v0_8/json/server_to_client.json` +- **Server-to-Client Schema, with standard catalog**: `@specification/v0_8/json/server_to_client_with_standard_catalog.json` +- **Client-to-Server Schema**: `@specification/v0_8/json/client_to_server.json` ## Running the Demos diff --git a/a2a_agents/python/a2ui_extension/src/a2ui/a2ui_extension.py b/a2a_agents/python/a2ui_extension/src/a2ui/a2ui_extension.py index 53f1ef99..37f444bc 100644 --- a/a2a_agents/python/a2ui_extension/src/a2ui/a2ui_extension.py +++ b/a2a_agents/python/a2ui_extension/src/a2ui/a2ui_extension.py @@ -29,7 +29,7 @@ SUPPORTED_CATALOG_IDS_KEY = "supportedCatalogIds" INLINE_CATALOGS_KEY = "inlineCatalogs" -STANDARD_CATALOG_ID = "https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json" +STANDARD_CATALOG_ID = "https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json" def create_a2ui_part(a2ui_data: dict[str, Any]) -> Part: """Creates an A2A Part containing A2UI data. diff --git a/docs/reference/components.md b/docs/reference/components.md index e51de6af..3476eb54 100644 --- a/docs/reference/components.md +++ b/docs/reference/components.md @@ -1,6 +1,6 @@ # Component Gallery -This page showcases all standard A2UI components with examples and usage patterns. For the complete technical specification, see the [Standard Catalog Definition](https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json). +This page showcases all standard A2UI components with examples and usage patterns. For the complete technical specification, see the [Standard Catalog Definition](https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json). ## Layout Components @@ -267,6 +267,6 @@ This launches a live gallery with all components, their variations, and interact ## Further Reading -- **[Standard Catalog Definition](../../specification/0.9/json/standard_catalog_definition.json)**: Complete technical specification +- **[Standard Catalog Definition](../../specification/v0_9/json/standard_catalog_definition.json)**: Complete technical specification - **[Custom Components Guide](../guides/custom-components.md)**: Build your own components - **[Theming Guide](../guides/theming.md)**: Style components to match your brand diff --git a/docs/reference/messages.md b/docs/reference/messages.md index d122cd7a..d3dd21ba 100644 --- a/docs/reference/messages.md +++ b/docs/reference/messages.md @@ -386,8 +386,8 @@ Remove a surface and all its components and data. All messages should be validated against: -- **[server_to_client.json](https://github.com/google/A2UI/blob/main/specification/0.8/json/server_to_client.json)**: Message envelope schema -- **[standard_catalog_definition.json](https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json)**: Component schemas +- **[server_to_client.json](https://github.com/google/A2UI/blob/main/specification/v0_8/json/server_to_client.json)**: Message envelope schema +- **[standard_catalog_definition.json](https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json)**: Component schemas ## Further Reading diff --git a/docs/specification/v0.8-a2a-extension.md b/docs/specification/v0.8-a2a-extension.md index c5aae221..8718295a 100644 --- a/docs/specification/v0.8-a2a-extension.md +++ b/docs/specification/v0.8-a2a-extension.md @@ -1,7 +1,7 @@ # A2UI Extension for A2A Protocol (v0.8) !!! info "Living Document" - This specification is automatically included from `specification/0.8/docs/a2ui_extension_specification.md`. Any updates to the specification will automatically appear here. + This specification is automatically included from `specification/v0_8/docs/a2ui_extension_specification.md`. Any updates to the specification will automatically appear here. !!! note "Version Compatibility" This extension specification applies to A2UI v0.8 and the A2A Protocol. For the base A2UI protocol, see [v0.8 Protocol Specification](v0.8-a2ui.md). @@ -12,4 +12,4 @@ --- ---8<-- "specification/0.8/docs/a2ui_extension_specification.md" +--8<-- "specification/v0_8/docs/a2ui_extension_specification.md" diff --git a/docs/specification/v0.8-a2ui.md b/docs/specification/v0.8-a2ui.md index 3299dcea..dc073039 100644 --- a/docs/specification/v0.8-a2ui.md +++ b/docs/specification/v0.8-a2ui.md @@ -4,7 +4,7 @@ Version 0.8 is the current stable release, recommended for production use. !!! info "Living Document" - This specification is automatically included from `specification/0.8/docs/a2ui_protocol.md`. Any updates to the specification will automatically appear here. + This specification is automatically included from `specification/v0_8/docs/a2ui_protocol.md`. Any updates to the specification will automatically appear here. **See also:** - [v0.9 Protocol Specification](v0.9-a2ui.md) (Draft) @@ -13,4 +13,4 @@ --- ---8<-- "specification/0.8/docs/a2ui_protocol.md" +--8<-- "specification/v0_8/docs/a2ui_protocol.md" diff --git a/docs/specification/v0.9-a2ui.md b/docs/specification/v0.9-a2ui.md index d8896797..cb189505 100644 --- a/docs/specification/v0.9-a2ui.md +++ b/docs/specification/v0.9-a2ui.md @@ -1,7 +1,7 @@ # A2UI Protocol v0.9 (Draft) !!! info "Living Document" - This specification is automatically included from `specification/0.9/docs/a2ui_protocol.md`. Any updates to the specification will automatically appear here. + This specification is automatically included from `specification/v0_9/docs/a2ui_protocol.md`. Any updates to the specification will automatically appear here. !!! warning "Draft Status" Version 0.9 is currently in draft status. For production use, consider [v0.8 (Stable)](v0.8-a2ui.md). @@ -12,4 +12,4 @@ --- ---8<-- "specification/0.9/docs/a2ui_protocol.md" +--8<-- "specification/v0_9/docs/a2ui_protocol.md" diff --git a/docs/specification/v0.9-evolution-guide.md b/docs/specification/v0.9-evolution-guide.md index 30319f4f..d120f9f1 100644 --- a/docs/specification/v0.9-evolution-guide.md +++ b/docs/specification/v0.9-evolution-guide.md @@ -1,7 +1,7 @@ # Evolution Guide: v0.8 → v0.9 !!! info "Living Document" - This guide is automatically included from `specification/0.9/docs/evolution_guide.md`. Any updates will automatically appear here. + This guide is automatically included from `specification/v0_9/docs/evolution_guide.md`. Any updates will automatically appear here. **Related Documentation:** - [A2UI Protocol v0.8](v0.8-a2ui.md) (Stable - what you're migrating from) @@ -9,4 +9,4 @@ --- ---8<-- "specification/0.9/docs/evolution_guide.md" +--8<-- "specification/v0_9/docs/evolution_guide.md" diff --git a/renderers/lit/package.json b/renderers/lit/package.json index 6cc360cb..e66477f1 100644 --- a/renderers/lit/package.json +++ b/renderers/lit/package.json @@ -30,9 +30,9 @@ }, "wireit": { "copy-spec": { - "command": "mkdir -p src/0.8/schemas && cp ../../specification/0.8/json/*.json src/0.8/schemas", + "command": "mkdir -p src/0.8/schemas && cp ../../specification/v0_8/json/*.json src/0.8/schemas", "files": [ - "../../specification/0.8/json/*.json" + "../../specification/v0_8/json/*.json" ], "output": [ "src/0.8/schemas/*.json" diff --git a/samples/agent/adk/rizzcharts/agent_executor.py b/samples/agent/adk/rizzcharts/agent_executor.py index de516cc4..f2365ee5 100644 --- a/samples/agent/adk/rizzcharts/agent_executor.py +++ b/samples/agent/adk/rizzcharts/agent_executor.py @@ -50,7 +50,7 @@ class RizzchartsAgentExecutor(A2aAgentExecutor): def __init__(self, base_url: str): self._base_url = base_url - spec_root = Path(__file__).parent / "../../../../specification/0.8/json" + spec_root = Path(__file__).parent / "../../../../specification/v0_8/json" self._component_catalog_builder = ComponentCatalogBuilder( a2ui_schema_path=str(spec_root.joinpath("server_to_client.json")), diff --git a/samples/agent/adk/rizzcharts/rizzcharts_catalog_definition.json b/samples/agent/adk/rizzcharts/rizzcharts_catalog_definition.json index 116d3815..88006a6f 100644 --- a/samples/agent/adk/rizzcharts/rizzcharts_catalog_definition.json +++ b/samples/agent/adk/rizzcharts/rizzcharts_catalog_definition.json @@ -1,6 +1,6 @@ { "components": { - "$ref": "../../../../specification/0.8/json/standard_catalog_definition.json#/components", + "$ref": "../../../../specification/v0_8/json/standard_catalog_definition.json#/components", "Canvas": { "type": "object", "description": "Renders the UI element in a stateful panel next to the chat window.", diff --git a/samples/client/angular/projects/orchestrator/src/server.ts b/samples/client/angular/projects/orchestrator/src/server.ts index 7f6ae883..70472047 100644 --- a/samples/client/angular/projects/orchestrator/src/server.ts +++ b/samples/client/angular/projects/orchestrator/src/server.ts @@ -62,7 +62,7 @@ app.post('/a2a', (req, res) => { metadata: { a2uiClientCapabilities: { supportedCatalogIds: [ - 'https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json', + 'https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json', ], }, }, diff --git a/samples/client/angular/projects/rizzcharts/src/components/toolbar/toolbar.ts b/samples/client/angular/projects/rizzcharts/src/components/toolbar/toolbar.ts index cd8ccecd..cc071982 100644 --- a/samples/client/angular/projects/rizzcharts/src/components/toolbar/toolbar.ts +++ b/samples/client/angular/projects/rizzcharts/src/components/toolbar/toolbar.ts @@ -37,7 +37,7 @@ export class Toolbar { catalogs = [ { - value: 'https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json', + value: 'https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json', viewValue: 'Standard' }, { diff --git a/specification/0.8/docs/a2ui_extension_specification.md b/specification/v0_8/docs/a2ui_extension_specification.md similarity index 97% rename from specification/0.8/docs/a2ui_extension_specification.md rename to specification/v0_8/docs/a2ui_extension_specification.md index 2d878286..98ecd7cb 100644 --- a/specification/0.8/docs/a2ui_extension_specification.md +++ b/specification/v0_8/docs/a2ui_extension_specification.md @@ -41,7 +41,7 @@ Example AgentExtension block: "required": false, "params": { "supportedCatalogIds": [ - "https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json", + "https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json", "https://my-company.com/a2ui/v0.8/my_custom_catalog.json" ], "acceptsInlineCatalogs": true diff --git a/specification/0.8/docs/a2ui_protocol.md b/specification/v0_8/docs/a2ui_protocol.md similarity index 99% rename from specification/0.8/docs/a2ui_protocol.md rename to specification/v0_8/docs/a2ui_protocol.md index 693a1bc2..b3f2da39 100644 --- a/specification/0.8/docs/a2ui_protocol.md +++ b/specification/v0_8/docs/a2ui_protocol.md @@ -167,7 +167,7 @@ A2UI's component model is designed for flexibility, separating the protocol from 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 `https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json`. +There is a **Standard Catalog** associated with each version of the A2UI protocol. For v0.8, its identifier is `https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json`. Catalog IDs are simple string identifiers. While they can be anything, it is conventional to use a URI within a domain that you own, to simplify debugging, avoid confusion, and avoid name 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. @@ -192,7 +192,7 @@ The server (agent) advertises its capabilities in its Agent Card as part of the "uri": "https://a2ui.org/a2a-extension/a2ui/v0.8", "params": { "supportedCatalogIds": [ - "https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json", + "https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json", "https://my-company.com/a2ui/v0.8/my_custom_catalog.json" ], "acceptsInlineCatalogs": true @@ -218,7 +218,7 @@ In **every** message sent to the server, the client includes an `a2uiClientCapab "metadata": { "a2uiClientCapabilities": { "supportedCatalogIds": [ - "https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json", + "https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json", "https://my-company.com/a2ui_catalogs/custom-reporting-catalog-1.2" ], "inlineCatalogs": [ @@ -249,7 +249,7 @@ The server receives the client's capabilities and chooses a catalog to use for a - `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 (`https://github.com/google/A2UI/blob/main/specification/0.8/json/standard_catalog_definition.json`). +If the `catalogId` is omitted, the client **MUST** default to the standard catalog for the protocol version (`https://github.com/google/A2UI/blob/main/specification/v0_8/json/standard_catalog_definition.json`). **Example `beginRendering` Message:** ```json diff --git a/specification/0.8/docs/custom_catalog_changes.md b/specification/v0_8/docs/custom_catalog_changes.md similarity index 100% rename from specification/0.8/docs/custom_catalog_changes.md rename to specification/v0_8/docs/custom_catalog_changes.md diff --git a/specification/0.8/eval/.env.example b/specification/v0_8/eval/.env.example similarity index 100% rename from specification/0.8/eval/.env.example rename to specification/v0_8/eval/.env.example diff --git a/specification/0.8/eval/.gitignore b/specification/v0_8/eval/.gitignore similarity index 100% rename from specification/0.8/eval/.gitignore rename to specification/v0_8/eval/.gitignore diff --git a/specification/0.8/eval/GEMINI.md b/specification/v0_8/eval/GEMINI.md similarity index 100% rename from specification/0.8/eval/GEMINI.md rename to specification/v0_8/eval/GEMINI.md diff --git a/specification/0.8/eval/README.md b/specification/v0_8/eval/README.md similarity index 100% rename from specification/0.8/eval/README.md rename to specification/v0_8/eval/README.md diff --git a/specification/0.8/eval/genkit.conf.js b/specification/v0_8/eval/genkit.conf.js similarity index 100% rename from specification/0.8/eval/genkit.conf.js rename to specification/v0_8/eval/genkit.conf.js diff --git a/specification/0.8/eval/package.json b/specification/v0_8/eval/package.json similarity index 100% rename from specification/0.8/eval/package.json rename to specification/v0_8/eval/package.json diff --git a/specification/0.8/eval/pnpm-lock.yaml b/specification/v0_8/eval/pnpm-lock.yaml similarity index 100% rename from specification/0.8/eval/pnpm-lock.yaml rename to specification/v0_8/eval/pnpm-lock.yaml diff --git a/specification/0.8/eval/pnpm-workspace.yaml b/specification/v0_8/eval/pnpm-workspace.yaml similarity index 100% rename from specification/0.8/eval/pnpm-workspace.yaml rename to specification/v0_8/eval/pnpm-workspace.yaml diff --git a/specification/0.8/eval/src/basic_schema_matcher.ts b/specification/v0_8/eval/src/basic_schema_matcher.ts similarity index 100% rename from specification/0.8/eval/src/basic_schema_matcher.ts rename to specification/v0_8/eval/src/basic_schema_matcher.ts diff --git a/specification/0.8/eval/src/dev.ts b/specification/v0_8/eval/src/dev.ts similarity index 100% rename from specification/0.8/eval/src/dev.ts rename to specification/v0_8/eval/src/dev.ts diff --git a/specification/0.8/eval/src/flows.ts b/specification/v0_8/eval/src/flows.ts similarity index 100% rename from specification/0.8/eval/src/flows.ts rename to specification/v0_8/eval/src/flows.ts diff --git a/specification/0.8/eval/src/index.ts b/specification/v0_8/eval/src/index.ts similarity index 100% rename from specification/0.8/eval/src/index.ts rename to specification/v0_8/eval/src/index.ts diff --git a/specification/0.8/eval/src/message_type_matcher.ts b/specification/v0_8/eval/src/message_type_matcher.ts similarity index 100% rename from specification/0.8/eval/src/message_type_matcher.ts rename to specification/v0_8/eval/src/message_type_matcher.ts diff --git a/specification/0.8/eval/src/models.ts b/specification/v0_8/eval/src/models.ts similarity index 100% rename from specification/0.8/eval/src/models.ts rename to specification/v0_8/eval/src/models.ts diff --git a/specification/0.8/eval/src/prompts.ts b/specification/v0_8/eval/src/prompts.ts similarity index 100% rename from specification/0.8/eval/src/prompts.ts rename to specification/v0_8/eval/src/prompts.ts diff --git a/specification/0.8/eval/src/schema_matcher.ts b/specification/v0_8/eval/src/schema_matcher.ts similarity index 100% rename from specification/0.8/eval/src/schema_matcher.ts rename to specification/v0_8/eval/src/schema_matcher.ts diff --git a/specification/0.8/eval/src/surface_update_schema_matcher.ts b/specification/v0_8/eval/src/surface_update_schema_matcher.ts similarity index 100% rename from specification/0.8/eval/src/surface_update_schema_matcher.ts rename to specification/v0_8/eval/src/surface_update_schema_matcher.ts diff --git a/specification/0.8/eval/src/validator.ts b/specification/v0_8/eval/src/validator.ts similarity index 100% rename from specification/0.8/eval/src/validator.ts rename to specification/v0_8/eval/src/validator.ts diff --git a/specification/0.8/eval/tsconfig.json b/specification/v0_8/eval/tsconfig.json similarity index 100% rename from specification/0.8/eval/tsconfig.json rename to specification/v0_8/eval/tsconfig.json diff --git a/specification/0.8/json/README.md b/specification/v0_8/json/README.md similarity index 100% rename from specification/0.8/json/README.md rename to specification/v0_8/json/README.md diff --git a/specification/0.8/json/a2ui_client_capabilities_schema.json b/specification/v0_8/json/a2ui_client_capabilities_schema.json similarity index 100% rename from specification/0.8/json/a2ui_client_capabilities_schema.json rename to specification/v0_8/json/a2ui_client_capabilities_schema.json diff --git a/specification/0.8/json/catalog_description_schema.json b/specification/v0_8/json/catalog_description_schema.json similarity index 100% rename from specification/0.8/json/catalog_description_schema.json rename to specification/v0_8/json/catalog_description_schema.json diff --git a/specification/0.8/json/client_to_server.json b/specification/v0_8/json/client_to_server.json similarity index 100% rename from specification/0.8/json/client_to_server.json rename to specification/v0_8/json/client_to_server.json diff --git a/specification/0.8/json/server_to_client.json b/specification/v0_8/json/server_to_client.json similarity index 100% rename from specification/0.8/json/server_to_client.json rename to specification/v0_8/json/server_to_client.json diff --git a/specification/0.8/json/server_to_client_with_standard_catalog.json b/specification/v0_8/json/server_to_client_with_standard_catalog.json similarity index 100% rename from specification/0.8/json/server_to_client_with_standard_catalog.json rename to specification/v0_8/json/server_to_client_with_standard_catalog.json diff --git a/specification/0.8/json/standard_catalog_definition.json b/specification/v0_8/json/standard_catalog_definition.json similarity index 100% rename from specification/0.8/json/standard_catalog_definition.json rename to specification/v0_8/json/standard_catalog_definition.json diff --git a/specification/0.9/docs/a2ui_extension_specification.md b/specification/v0_9/docs/a2ui_extension_specification.md similarity index 96% rename from specification/0.9/docs/a2ui_extension_specification.md rename to specification/v0_9/docs/a2ui_extension_specification.md index b0184366..cc96b181 100644 --- a/specification/0.9/docs/a2ui_extension_specification.md +++ b/specification/v0_9/docs/a2ui_extension_specification.md @@ -40,7 +40,7 @@ Example AgentExtension block: "required": false, "params": { "supportedCatalogIds": [ - "https://a2ui.dev/specification/0.9/standard_catalog.json", + "https://a2ui.dev/specification/v0_9/standard_catalog.json", "https://my-company.com/a2ui/v0.9/my_custom_catalog.json" ], "acceptsInlineCatalogs": true @@ -78,7 +78,7 @@ Example A2UI DataPart: "data": { "createSurface": { "surfaceId": "user_profile_surface", - "catalogId": "https://a2ui.dev/specification/0.9/standard_catalog.json" + "catalogId": "https://a2ui.dev/specification/v0_9/standard_catalog.json" } }, "kind": "data", diff --git a/specification/0.9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md similarity index 99% rename from specification/0.9/docs/a2ui_protocol.md rename to specification/v0_9/docs/a2ui_protocol.md index 70ebe9d0..1e1ade95 100644 --- a/specification/0.9/docs/a2ui_protocol.md +++ b/specification/v0_9/docs/a2ui_protocol.md @@ -124,7 +124,7 @@ This message signals the client to create a new surface and begin rendering it. { "createSurface": { "surfaceId": "user_profile_card", - "catalogId": "https://a2ui.dev/specification/0.9/standard_catalog.json" + "catalogId": "https://a2ui.dev/specification/v0_9/standard_catalog.json" } } ``` @@ -261,7 +261,7 @@ If multiple configurations apply to the same data (e.g., one for `/` and one for The following example demonstrates a complete interaction to render a Contact Form, expressed as a JSONL stream. ```jsonl -{"createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.dev/specification/0.9/standard_catalog.json"}} +{"createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.dev/specification/v0_9/standard_catalog.json"}} {"updateComponents":{"surfaceId":"contact_form_1","components":[{"id":"root","component":"Card","child":"form_container"},{"id":"form_container","component":"Column","children":["header_row","name_row","email_group","phone_group","pref_group","divider_1","newsletter_checkbox","submit_button"],"justify":"start","align":"stretch"},{"id":"header_row","component":"Row","children":["header_icon","header_text"],"align":"center"},{"id":"header_icon","component":"Icon","name":"mail"},{"id":"header_text","component":"Text","text":"# Contact Us","variant":"h2"},{"id":"name_row","component":"Row","children":["first_name_group","last_name_group"],"justify":"spaceBetween"},{"id":"first_name_group","component":"Column","children":["first_name_label","first_name_field"],"weight":1},{"id":"first_name_label","component":"Text","text":"First Name","variant":"caption"},{"id":"first_name_field","component":"TextField","label":"First Name","value":{"path":"/contact/firstName"},"variant":"shortText"},{"id":"last_name_group","component":"Column","children":["last_name_label","last_name_field"],"weight":1},{"id":"last_name_label","component":"Text","text":"Last Name","variant":"caption"},{"id":"last_name_field","component":"TextField","label":"Last Name","value":{"path":"/contact/lastName"},"variant":"shortText"},{"id":"email_group","component":"Column","children":["email_label","email_field"]},{"id":"email_label","component":"Text","text":"Email Address","variant":"caption"},{"id":"email_field","component":"TextField","label":"Email","value":{"path":"/contact/email"},"variant":"shortText","checks":[{"call":"required","message":"Email is required."},{"call":"email","message":"Please enter a valid email address."}]},{"id":"phone_group","component":"Column","children":["phone_label","phone_field"]},{"id":"phone_label","component":"Text","text":"Phone Number","variant":"caption"},{"id":"phone_field","component":"TextField","label":"Phone","value":{"path":"/contact/phone"},"variant":"shortText","checks":[{"call":"regex","args":{"pattern":"^\\d{10}$"},"message":"Phone number must be 10 digits."}]},{"id":"pref_group","component":"Column","children":["pref_label","pref_picker"]},{"id":"pref_label","component":"Text","text":"Preferred Contact Method","variant":"caption"},{"id":"pref_picker","component":"ChoicePicker","variant":"mutuallyExclusive","options":[{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"SMS","value":"sms"}],"value":{"path":"/contact/preference"}},{"id":"divider_1","component":"Divider","axis":"horizontal"},{"id":"newsletter_checkbox","component":"CheckBox","label":"Subscribe to our newsletter","value":{"path":"/contact/subscribe"}},{"id":"submit_button_label","component":"Text","text":"Send Message"},{"id":"submit_button","component":"Button","child":"submit_button_label","primary":true,"action":{"name":"submitContactForm","context":{"formId":"contact_form_1","clientTime":{"call":"now","returnType":"string"},"isNewsletterSubscribed":{"path":"/contact/subscribe"}}}}]}} {"updateDataModel":{"surfaceId":"contact_form_1","actorId":"agent-1","updates":[{"path":"/contact","value":{"firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"1234567890","preference":["email"],"subscribe":true},"hlc":"2026-01-12T16:34:29.000Z:0001:agent-1"}],"versions":{"agent-1":"2026-01-12T16:34:29.000Z:0001:agent-1"}}} ``` diff --git a/specification/0.9/docs/evolution_guide.md b/specification/v0_9/docs/evolution_guide.md similarity index 99% rename from specification/0.9/docs/evolution_guide.md rename to specification/v0_9/docs/evolution_guide.md index b8913217..141791d0 100644 --- a/specification/0.9/docs/evolution_guide.md +++ b/specification/v0_9/docs/evolution_guide.md @@ -104,7 +104,7 @@ Version 0.9 represents a fundamental philosophical shift from "Structured Output { "createSurface": { "surfaceId": "user_profile_card", - "catalogId": "https://a2ui.dev/specification/0.9/standard_catalog.json" + "catalogId": "https://a2ui.dev/specification/v0_9/standard_catalog.json" } } ``` diff --git a/specification/0.9/eval/.env.example b/specification/v0_9/eval/.env.example similarity index 100% rename from specification/0.9/eval/.env.example rename to specification/v0_9/eval/.env.example diff --git a/specification/0.9/eval/.gitignore b/specification/v0_9/eval/.gitignore similarity index 100% rename from specification/0.9/eval/.gitignore rename to specification/v0_9/eval/.gitignore diff --git a/specification/0.9/eval/README.md b/specification/v0_9/eval/README.md similarity index 100% rename from specification/0.9/eval/README.md rename to specification/v0_9/eval/README.md diff --git a/specification/0.9/eval/genkit.conf.js b/specification/v0_9/eval/genkit.conf.js similarity index 100% rename from specification/0.9/eval/genkit.conf.js rename to specification/v0_9/eval/genkit.conf.js diff --git a/specification/0.9/eval/package.json b/specification/v0_9/eval/package.json similarity index 100% rename from specification/0.9/eval/package.json rename to specification/v0_9/eval/package.json diff --git a/specification/0.9/eval/pnpm-lock.yaml b/specification/v0_9/eval/pnpm-lock.yaml similarity index 100% rename from specification/0.9/eval/pnpm-lock.yaml rename to specification/v0_9/eval/pnpm-lock.yaml diff --git a/specification/0.9/eval/pnpm-workspace.yaml b/specification/v0_9/eval/pnpm-workspace.yaml similarity index 100% rename from specification/0.9/eval/pnpm-workspace.yaml rename to specification/v0_9/eval/pnpm-workspace.yaml diff --git a/specification/0.9/eval/src/ai.ts b/specification/v0_9/eval/src/ai.ts similarity index 100% rename from specification/0.9/eval/src/ai.ts rename to specification/v0_9/eval/src/ai.ts diff --git a/specification/0.9/eval/src/analysis_flow.ts b/specification/v0_9/eval/src/analysis_flow.ts similarity index 100% rename from specification/0.9/eval/src/analysis_flow.ts rename to specification/v0_9/eval/src/analysis_flow.ts diff --git a/specification/0.9/eval/src/dev.ts b/specification/v0_9/eval/src/dev.ts similarity index 100% rename from specification/0.9/eval/src/dev.ts rename to specification/v0_9/eval/src/dev.ts diff --git a/specification/0.9/eval/src/evaluation_flow.ts b/specification/v0_9/eval/src/evaluation_flow.ts similarity index 100% rename from specification/0.9/eval/src/evaluation_flow.ts rename to specification/v0_9/eval/src/evaluation_flow.ts diff --git a/specification/0.9/eval/src/evaluator.ts b/specification/v0_9/eval/src/evaluator.ts similarity index 100% rename from specification/0.9/eval/src/evaluator.ts rename to specification/v0_9/eval/src/evaluator.ts diff --git a/specification/0.9/eval/src/generation_flow.ts b/specification/v0_9/eval/src/generation_flow.ts similarity index 98% rename from specification/0.9/eval/src/generation_flow.ts rename to specification/v0_9/eval/src/generation_flow.ts index cf1c598a..a5d9018a 100644 --- a/specification/0.9/eval/src/generation_flow.ts +++ b/specification/v0_9/eval/src/generation_flow.ts @@ -41,7 +41,7 @@ export const componentGeneratorFlow = ai.defineFlow( The output MUST be a series of JSON objects, each enclosed in a markdown code block (or a single block with multiple objects). Standard Instructions: -1. Generate a 'createSurface' message with surfaceId 'main' and catalogId 'https://a2ui.dev/specification/0.9/standard_catalog.json'. +1. Generate a 'createSurface' message with surfaceId 'main' and catalogId 'https://a2ui.dev/specification/v0_9/standard_catalog.json'. 2. Generate a 'updateComponents' message with surfaceId 'main' containing the requested UI. 3. Ensure all component children are referenced by ID (using the 'children' or 'child' property with IDs), NOT nested inline as objects. 4. If the request involves data binding, you may also generate 'updateDataModel' messages. diff --git a/specification/0.9/eval/src/generator.ts b/specification/v0_9/eval/src/generator.ts similarity index 100% rename from specification/0.9/eval/src/generator.ts rename to specification/v0_9/eval/src/generator.ts diff --git a/specification/0.9/eval/src/index.ts b/specification/v0_9/eval/src/index.ts similarity index 100% rename from specification/0.9/eval/src/index.ts rename to specification/v0_9/eval/src/index.ts diff --git a/specification/0.9/eval/src/logger.ts b/specification/v0_9/eval/src/logger.ts similarity index 100% rename from specification/0.9/eval/src/logger.ts rename to specification/v0_9/eval/src/logger.ts diff --git a/specification/0.9/eval/src/models.ts b/specification/v0_9/eval/src/models.ts similarity index 100% rename from specification/0.9/eval/src/models.ts rename to specification/v0_9/eval/src/models.ts diff --git a/specification/0.9/eval/src/prompts.ts b/specification/v0_9/eval/src/prompts.ts similarity index 100% rename from specification/0.9/eval/src/prompts.ts rename to specification/v0_9/eval/src/prompts.ts diff --git a/specification/0.9/eval/src/rateLimiter.ts b/specification/v0_9/eval/src/rateLimiter.ts similarity index 100% rename from specification/0.9/eval/src/rateLimiter.ts rename to specification/v0_9/eval/src/rateLimiter.ts diff --git a/specification/0.9/eval/src/types.ts b/specification/v0_9/eval/src/types.ts similarity index 100% rename from specification/0.9/eval/src/types.ts rename to specification/v0_9/eval/src/types.ts diff --git a/specification/0.9/eval/src/utils.ts b/specification/v0_9/eval/src/utils.ts similarity index 100% rename from specification/0.9/eval/src/utils.ts rename to specification/v0_9/eval/src/utils.ts diff --git a/specification/0.9/eval/src/validator.ts b/specification/v0_9/eval/src/validator.ts similarity index 98% rename from specification/0.9/eval/src/validator.ts rename to specification/v0_9/eval/src/validator.ts index b6b46464..e98aae7d 100644 --- a/specification/0.9/eval/src/validator.ts +++ b/specification/v0_9/eval/src/validator.ts @@ -35,7 +35,7 @@ export class Validator { this.ajv.addSchema(schema, name); } this.validateFn = this.ajv.getSchema( - "https://a2ui.dev/specification/0.9/server_to_client.json" + "https://a2ui.dev/specification/v0_9/server_to_client.json" ); } @@ -67,7 +67,7 @@ export class Validator { // to avoid noisy "oneOf" errors. let validated = false; const schemaUri = - "https://a2ui.dev/specification/0.9/server_to_client.json"; + "https://a2ui.dev/specification/v0_9/server_to_client.json"; if (message.createSurface) { validated = this.ajv.validate( @@ -254,7 +254,7 @@ export class Validator { if (this.ajv && c.component) { const componentType = c.component; const schemaUri = - "https://a2ui.dev/specification/0.9/standard_catalog.json"; + "https://a2ui.dev/specification/v0_9/standard_catalog.json"; const defRef = `${schemaUri}#/components/${componentType}`; diff --git a/specification/0.9/eval/tsconfig.json b/specification/v0_9/eval/tsconfig.json similarity index 100% rename from specification/0.9/eval/tsconfig.json rename to specification/v0_9/eval/tsconfig.json diff --git a/specification/0.9/json/a2ui_client_capabilities_schema.json b/specification/v0_9/json/a2ui_client_capabilities_schema.json similarity index 100% rename from specification/0.9/json/a2ui_client_capabilities_schema.json rename to specification/v0_9/json/a2ui_client_capabilities_schema.json diff --git a/specification/0.9/json/client_to_server.json b/specification/v0_9/json/client_to_server.json similarity index 100% rename from specification/0.9/json/client_to_server.json rename to specification/v0_9/json/client_to_server.json diff --git a/specification/0.9/json/common_types.json b/specification/v0_9/json/common_types.json similarity index 99% rename from specification/0.9/json/common_types.json rename to specification/v0_9/json/common_types.json index d4b5f3d8..b416d486 100644 --- a/specification/0.9/json/common_types.json +++ b/specification/v0_9/json/common_types.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://a2ui.dev/specification/0.9/common_types.json", + "$id": "https://a2ui.dev/specification/v0_9/common_types.json", "title": "A2UI Common Types", "description": "Common type definitions used across A2UI schemas.", "$defs": { diff --git a/specification/0.9/json/server_to_client.json b/specification/v0_9/json/server_to_client.json similarity index 98% rename from specification/0.9/json/server_to_client.json rename to specification/v0_9/json/server_to_client.json index 204cd576..65e71831 100644 --- a/specification/0.9/json/server_to_client.json +++ b/specification/v0_9/json/server_to_client.json @@ -1,6 +1,6 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://a2ui.dev/specification/0.9/server_to_client.json", + "$id": "https://a2ui.dev/specification/v0_9/server_to_client.json", "title": "A2UI Message Schema", "description": "Describes a JSON payload for an A2UI (Agent to UI) message, which is used to dynamically construct and update user interfaces.", "type": "object", diff --git a/specification/0.9/json/standard_catalog.json b/specification/v0_9/json/standard_catalog.json similarity index 99% rename from specification/0.9/json/standard_catalog.json rename to specification/v0_9/json/standard_catalog.json index 7911b898..23c2a785 100644 --- a/specification/0.9/json/standard_catalog.json +++ b/specification/v0_9/json/standard_catalog.json @@ -1,9 +1,9 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://a2ui.dev/specification/0.9/standard_catalog.json", + "$id": "https://a2ui.dev/specification/v0_9/standard_catalog.json", "title": "A2UI Standard Catalog", "description": "Unified catalog of standard A2UI components and functions.", - "catalogId": "https://a2ui.dev/specification/0.9/standard_catalog.json", + "catalogId": "https://a2ui.dev/specification/v0_9/standard_catalog.json", "components": { "Text": { "type": "object", diff --git a/specification/0.9/json/standard_catalog_rules.txt b/specification/v0_9/json/standard_catalog_rules.txt similarity index 100% rename from specification/0.9/json/standard_catalog_rules.txt rename to specification/v0_9/json/standard_catalog_rules.txt diff --git a/specification/0.9/test/README.md b/specification/v0_9/test/README.md similarity index 81% rename from specification/0.9/test/README.md rename to specification/v0_9/test/README.md index 858b2a9e..8ac3c5a7 100644 --- a/specification/0.9/test/README.md +++ b/specification/v0_9/test/README.md @@ -12,7 +12,7 @@ This directory contains test cases and a runner for validating the A2UI JSON sch To speed up test execution, install the dependencies locally: ```bash -cd specification/0.9/test +cd specification/v0_9/test pnpm install ``` @@ -21,12 +21,12 @@ pnpm install Run the Python test script from the repository root or the test directory: ```bash -python3 specification/0.9/test/run_tests.py +python3 specification/v0_9/test/run_tests.py ``` The script will: -1. Load all schemas from `specification/0.9/json`. -2. Execute all test suites defined in `specification/0.9/test/cases/*.json`. +1. Load all schemas from `specification/v0_9/json`. +2. Execute all test suites defined in `specification/v0_9/test/cases/*.json`. 3. Report pass/fail status for each test case. ## Adding Tests diff --git a/specification/0.9/test/cases/button_checks.json b/specification/v0_9/test/cases/button_checks.json similarity index 100% rename from specification/0.9/test/cases/button_checks.json rename to specification/v0_9/test/cases/button_checks.json diff --git a/specification/0.9/test/cases/checkable_components.json b/specification/v0_9/test/cases/checkable_components.json similarity index 100% rename from specification/0.9/test/cases/checkable_components.json rename to specification/v0_9/test/cases/checkable_components.json diff --git a/specification/0.9/test/cases/client_messages.json b/specification/v0_9/test/cases/client_messages.json similarity index 100% rename from specification/0.9/test/cases/client_messages.json rename to specification/v0_9/test/cases/client_messages.json diff --git a/specification/0.9/test/cases/contact_form_example.jsonl b/specification/v0_9/test/cases/contact_form_example.jsonl similarity index 98% rename from specification/0.9/test/cases/contact_form_example.jsonl rename to specification/v0_9/test/cases/contact_form_example.jsonl index 0c0a0006..1eb1cbc2 100644 --- a/specification/0.9/test/cases/contact_form_example.jsonl +++ b/specification/v0_9/test/cases/contact_form_example.jsonl @@ -1,4 +1,4 @@ -{"createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.dev/specification/0.9/standard_catalog.json"}} +{"createSurface":{"surfaceId":"contact_form_1","catalogId":"https://a2ui.dev/specification/v0_9/standard_catalog.json"}} {"updateComponents":{"surfaceId":"contact_form_1","components":[{"id":"root","component":"Card","child":"form_container"},{"id":"form_container","component":"Column","children":["header_row","name_row","email_group","phone_group","pref_group","divider_1","newsletter_checkbox","submit_button"],"justify":"start","align":"stretch"},{"id":"header_row","component":"Row","children":["header_icon","header_text"],"align":"center"},{"id":"header_icon","component":"Icon","name":"mail"},{"id":"header_text","component":"Text","text":"# Contact Us","variant":"h2"},{"id":"name_row","component":"Row","children":["first_name_group","last_name_group"],"justify":"spaceBetween"},{"id":"first_name_group","component":"Column","children":["first_name_label","first_name_field"],"weight":1},{"id":"first_name_label","component":"Text","text":"First Name","variant":"caption"},{"id":"first_name_field","component":"TextField","label":"First Name","value":{"path":"/contact/firstName"},"variant":"shortText"},{"id":"last_name_group","component":"Column","children":["last_name_label","last_name_field"],"weight":1},{"id":"last_name_label","component":"Text","text":"Last Name","variant":"caption"},{"id":"last_name_field","component":"TextField","label":"Last Name","value":{"path":"/contact/lastName"},"variant":"shortText"},{"id":"email_group","component":"Column","children":["email_label","email_field"]},{"id":"email_label","component":"Text","text":"Email Address","variant":"caption"},{"id":"email_field","component":"TextField","label":"Email","value":{"path":"/contact/email"},"variant":"shortText","checks":[{"call":"required","message":"Email is required."},{"call":"email","message":"Please enter a valid email address."}]},{"id":"phone_group","component":"Column","children":["phone_label","phone_field"]},{"id":"phone_label","component":"Text","text":"Phone Number","variant":"caption"},{"id":"phone_field","component":"TextField","label":"Phone","value":{"path":"/contact/phone"},"variant":"shortText","checks":[{"call":"regex","args":{"pattern":"^\\d{10}$"},"message":"Phone number must be 10 digits."}]},{"id":"pref_group","component":"Column","children":["pref_label","pref_picker"]},{"id":"pref_label","component":"Text","text":"Preferred Contact Method","variant":"caption"},{"id":"pref_picker","component":"ChoicePicker","variant":"mutuallyExclusive","options":[{"label":"Email","value":"email"},{"label":"Phone","value":"phone"},{"label":"SMS","value":"sms"}],"value":{"path":"/contact/preference"}},{"id":"divider_1","component":"Divider","axis":"horizontal"},{"id":"newsletter_checkbox","component":"CheckBox","label":"Subscribe to our newsletter","value":{"path":"/contact/subscribe"}},{"id":"submit_button_label","component":"Text","text":"Send Message"},{"id":"submit_button","component":"Button","child":"submit_button_label","primary":true,"action":{"name":"submitContactForm","context":{"formId":"contact_form_1","clientTime":{"call":"now","returnType":"string"},"isNewsletterSubscribed":{"path":"/contact/subscribe"}}}}]}} {"updateDataModel":{"surfaceId":"contact_form_1","path":"/contact","value":{"firstName":"John","lastName":"Doe","email":"john.doe@example.com","phone":"1234567890","preference":["email"],"subscribe":true}}} {"deleteSurface":{"surfaceId":"contact_form_1"}} diff --git a/specification/0.9/test/cases/contact_form_example_test.json b/specification/v0_9/test/cases/contact_form_example_test.json similarity index 97% rename from specification/0.9/test/cases/contact_form_example_test.json rename to specification/v0_9/test/cases/contact_form_example_test.json index ef59a602..db2e25f0 100644 --- a/specification/0.9/test/cases/contact_form_example_test.json +++ b/specification/v0_9/test/cases/contact_form_example_test.json @@ -7,7 +7,7 @@ "data": { "createSurface": { "surfaceId": "contact_form_1", - "catalogId": "https://a2ui.dev/specification/0.9/standard_catalog.json" + "catalogId": "https://a2ui.dev/specification/v0_9/standard_catalog.json" } } }, diff --git a/specification/0.9/test/package.json b/specification/v0_9/test/package.json similarity index 100% rename from specification/0.9/test/package.json rename to specification/v0_9/test/package.json diff --git a/specification/0.9/test/run_tests.py b/specification/v0_9/test/run_tests.py similarity index 100% rename from specification/0.9/test/run_tests.py rename to specification/v0_9/test/run_tests.py