spec(v1.0): separate pure A2UI protocol from A2A transport extensions

[gspencergoog]

Summary

This pull request reorganizes the version 1.0 candidate specification directory to establish a clean boundary between the core, transport-agnostic A2UI (Agent-to-UI) protocol and transport-specific extensions, while standardizing core capabilities and data synchronization schemas at the protocol layer.

It addresses PR review feedback by:

1. Keeping capabilities exchange and data model synchronization schemas in the core protocol, refactored to be completely transport-agnostic (useful for AG-UI, MCP, and other transports).
2. Grouping only transport-specific message packet framing and list wrappers inside the A2A extension.

Reorganized Directory Structure

specification/v1_0/
  README.md                         * Focuses on pure A2UI and points to A2A extensions
  catalogs/
    basic/
      catalog.json                  * Pure A2UI standard component catalog
  docs/
    a2ui_protocol.md                * Pure A2UI protocol (retains transport-agnostic capabilities/metadata section)
    a2ui_custom_functions.md        * Pure A2UI custom functions guide
    basic_catalog_implementation_guide.md * Pure A2UI rendering guide
    renderer_guide.md               * Pure A2UI architecture guide
    evolution_guide.md              * Pure A2UI version evolution guide
  json/
    common_types.json               * Pure A2UI core types
    server_to_client.json           * Pure A2UI server-to-client envelopes
    client_to_server.json           * Pure A2UI client-to-server envelopes
    catalog_definition.json         * Standalone A2UI catalog schema (extracted from capabilities)
    sample.json                     * Pure A2UI sample envelope
    client_capabilities.json        * Core A2UI client capabilities schema (restored to core)
    server_capabilities.json        * Core A2UI server capabilities schema (restored to core)
    client_data_model.json          * Core A2UI client data model schema (restored to core)
  
  extensions/
    a2a/                            * Dedicated A2A extension directory
      docs/
        a2ui_extension_specification.md * Relocated and expanded A2A extension spec
      json/
        server_to_client_list.json  * Relocated A2A server-to-client array schema
        server_to_client_list_wrapper.json * Relocated A2A server-to-client object wrapper
        client_to_server_list.json  * Relocated A2A client-to-server array schema
        client_to_server_list_wrapper.json * Relocated A2A client-to-server object wrapper
  
  test/
    run_tests.py                    * Updated to reference the new paths and validate all schemas

Changes

• Restructured Transport Bindings in Core Spec: Restructured the transport bindings in a2ui_protocol.md to provide clean, distinct, peer subsections for AG-UI, A2A, and MCP bindings, elevating MCP to a primary transport.
• Restored Generic Capabilities & Metadata:
  • Restored and refactored the Capabilities and metadata section in a2ui_protocol.md to describe capabilities and data models as transport-agnostic metadata payloads.
  • Restored client_capabilities.json, server_capabilities.json, and client_data_model.json to the core json/ folder, updating their $id URLs and making descriptions transport-independent.
• Extracted catalog schema: Created a new, core catalog_definition.json schema containing the standalone Catalog, FunctionDefinition, and FunctionCallValidationSchema definitions.
• Relocated A2A packet framing schemas: Moved A2A-specific message list wrappers and list wrapper schemas into the extensions/a2a/json/ subdirectory.
• Consolidated A2A extension documentation: Relocated and expanded a2ui_extension_specification.md to focus specifically on the A2A message list wrapping, mapping, and capabilities exchange.
• Aligned test runner: Updated run_tests.py to validate catalogs directly against catalog_definition.json and to validate the restored core capability schemas and A2A list schemas.
• Added comprehensive schema validation tests: Expanded the test runner with validate_a2a_schemas() and validate_sample_schema() suites, achieving 100% test coverage for all schema files in the specification.
• Aligned website build: Updated the living document notice and Markdown snippet include path (--8<--) inside v1.0-a2ui-extension-specification.md.

Impact & Risks

There are no breaking changes to the wire formats, validation schemas, or runtime behavior of the protocol:

• The core A2UI envelope structures and messages are completely unchanged.
• The A2A message list structures and metadata properties remain identical.
• This is an editorial and directory reorganization only; backward and forward compatibility are preserved.

Testing

Verified the reorganization by running the expanded specification validation test suite locally:

• All 129 tests successfully passed with 0 failures.
• Verification includes:
  • 123 standard test cases (buttons, catalogs, etc.).
  • 1 core sample.json schema validation check.
  • 5 dedicated A2A capability and list schema validation checks.
• To run the tests, execute: python3 run_tests.py inside specification/v1_0/test/.