spec(v1.0): Implement Strict Catalog JSON Schema Restrictions and Consolidation

[jacobsimionato]

Description

This pull request implements strict JSON Schema restrictions on component and function catalogs as proposed under A2UI v1.0, and resolves a schema discrepancy regarding surfaceProperties.

These structural constraints are designed to allow catalog files (catalog.json) to be translated reliably into alternative LLM-friendly DSL formats (e.g., HTML-like XML or compact functional/programmatic DSLs) and directly mapped to type-safe client SDK models.

Closes #1627

Rationale

• Alternative DSL support: Unconstrained JSON schemas make parsing and compiling to non-JSON target structures extremely complex. Strict structural rules ensure predictability for AST-based compilers.
• SDK alignment: Restricting the JSON Schema structure guarantees bidirectional mapping to Kotlin, Swift, or Python classes, eliminating the fragile code paths currently needed to support unconstrained JSON Schemas.
• Validation correction: Resolves a mismatch where surfaceProperties was expected at the top level of the Catalog object in client_capabilities.json but implemented inside $defs in actual catalogs.

Detailed Breakdown of Changes

1. JSON Schema Update (client_capabilities.json):
   • Moved surfaceProperties under the Catalog $defs property as a reference to a JSON Schema itself, correcting the mismatch.
   • Constrained $defs in Catalog to exclusively permit the standard keys: anyComponent, anyFunction, and surfaceProperties.
2. Catalog Refactoring (catalog.json):
   • Refactored basic and minimal catalogs:
     • Deleted the CatalogComponentCommon helper definition.
     • Inlined the standard relative layout "weight" property schema directly within all individual component definitions.
3. Protocol Documentation (a2ui_protocol.md):
   • Documented all catalog structural restrictions under a new section Catalog JSON Schema Structural Restrictions in the v1.0 protocol document.
   • Documented the established unwritten rules under Catalog Conventions (The "Unwritten Rules").

Verification & Testing

To verify these changes locally:

1. Run the python validation test suite:

   python3 specification/v1_0/test/run_tests.py

2. Verify that all 124 validation tests pass successfully with 0 failures, confirming that all refactored catalogs validate cleanly against the consolidated schema in client_capabilities.json and follow the strict identifier naming rules.

[gemini-code-assist]

Code Review

This pull request refactors the catalog schemas by inlining the layout weight property directly into individual components and removing the shared CatalogComponentCommon definition, aligning with new structural restrictions documented in a2ui_protocol.md. Additionally, client_capabilities.json has been updated to strictly define $defs properties. The review feedback suggests two key improvements: expanding the documented list of allowed external $ref targets in a2ui_protocol.md to include ComponentCommon, Checkable, and Action, and tightening the anyComponent and anyFunction schemas in client_capabilities.json by referencing the JSON Schema draft-2020-12 meta-schema.

[gemini-code-assist]

The list of allowed external $ref targets from common_types.json is missing several schemas that are actively used in the standard catalogs:

• ComponentCommon (used by all components for baseline identity and accessibility attributes)
• Checkable (used by input components and buttons for client-side checks)
• Action (used by buttons to define interaction handlers)

To ensure the documentation is complete and accurate, please add these schemas to the allowed list.

Suggested change:

   - External `$ref` targets MUST reference the standard types inside `common_types.json` (`https://a2ui.org/specification/v1_0/common_types.json#/$defs/...`), limited to the following allowed schemas:
     - `ComponentId`
     - `ChildList`
     - `DynamicString`
     - `DynamicNumber`
     - `DynamicBoolean`
     - `DynamicStringList`
     - `DynamicValue`
     - `CheckRule`
     - `ComponentCommon`
     - `Checkable`
     - `Action`

[gemini-code-assist]

The anyComponent and anyFunction schemas are defined with a loose "type": "object". Since they are themselves JSON Schemas that validate components and functions, they should be defined as references to the JSON Schema draft-2020-12 meta-schema. This ensures strictness and consistency with surfaceProperties (which correctly uses "$ref": "https://json-schema.org/draft/2020-12/schema").

            "anyComponent": {
              "title": "A2UI Any Component Schema",
              "description": "Unified validation schema for all components.",
              "$ref": "https://json-schema.org/draft/2020-12/schema"
            },
            "anyFunction": {
              "title": "A2UI Any Function Schema",
              "description": "Unified validation schema for all functions.",
              "$ref": "https://json-schema.org/draft/2020-12/schema"
            }