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.

[gspencergoog]

Instead of a list that needs to be maintained, couldn't you say:

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:
	- External `$ref` targets MUST only reference the standard types inside `common_types.json` (`https://a2ui.org/specification/v1_0/common_types.json#/$defs/...`), and is limited to that set of schemas.

Then we could avoid the list. I just worry that it will immediately be out of date.