fix(spec-v1.0): remove surfaceProperties from v1.0 specification (#2126) - #2129
Conversation
…ect#2126 Initialize CODING_AGENT_LOG.md to track core actions and progress toward resolving issue a2ui-project#2126, along with bin/gh wrapper script for restricted GitHub CLI interactions.
…i-project#2126) ## Summary Removes `surfaceProperties` from the A2UI v1.0 protocol specification, catalog definitions, and documentation, cleanly separating component layout from branding. ## Changes - **Catalog Definitions (`catalog_definition.json`, `catalogs/basic/catalog.json`, `test/testing_catalog.json`)**: Removed `surfaceProperties` schema definitions from `$defs`. - **Envelope Schema (`agent_to_renderer.json`)**: Removed the `surfaceProperties` property from `CreateSurfaceMessage`. - **Documentation (`a2ui_protocol.md`, `evolution_guide.md`)**: Removed all references, examples, and descriptions of `surfaceProperties`. Updated the evolution guide to indicate that `theme` and `primaryColor` were removed rather than replaced. - **Evaluation & Validation (`eval/src/types.ts`, `eval/src/validator.ts`)**: Removed `surfaceProperties` from `CatalogSchema` and from the allowed properties in `validateCreateSurface`. - **Tests**: Deleted `surface_properties_validation.json` and verified all 134 remaining v1.0 specification test cases pass cleanly. - **Coding Agent Log (`CODING_AGENT_LOG.md`)**: Updated activity log with completed tasks and test results. Closes a2ui-project#2126 TAG=agy CONV=564f1e1b-9755-4c91-a59a-e77c8c281834
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request removes surfaceProperties from the v1.0 specification, including its definitions in JSON schemas, documentation, TypeScript validator types, and test cases. While the documentation has been updated in several places, a review comment points out that the 'Surface Properties' section at the end of a2ui_protocol.md was missed and should also be removed to ensure complete cleanup.
| - `catalogId` (string, optional): A string that uniquely identifies the default catalog (components and functions) used for this surface. Note that `catalogId` is a string identifier, not a resolvable URI; while it is conventionally formatted as a URI (e.g., `https://mycompany.com/1.0/somecatalog`) to avoid naming collisions across organizations, it does not need to point to any deployed resource or downloadable file. Components and function calls on this surface that do not explicitly specify their own `catalogId` will use this surface-level default `catalogId`. | ||
|
|
||
| - `surfaceProperties` (object, optional): A JSON object containing surface properties (e.g., `agentDisplayName`) defined in the catalog's surfaceProperties schema. | ||
| - `sendDataModel` (boolean, optional): If true, the renderer will send the full data model of this surface in the metadata of every message sent to the agent (via the Transport's metadata mechanism). This ensures the surface owner receives the full current state of the UI alongside the user's action or query. Defaults to false. |
There was a problem hiding this comment.
While surfaceProperties has been removed from the createSurface properties list here, the Surface Properties section at the end of this document (lines 1046–1059) was not removed. It still describes iconUrl and agentDisplayName as surface properties. Please remove that section to fully complete the removal of surfaceProperties from the documentation.
There was a problem hiding this comment.
Oh, yes, that seems like it should have been updated a while ago for the names, but now should be entirely removed.
There was a problem hiding this comment.
Done! Entirely removed the Surface Properties section from a2ui_protocol.md.
| }, | ||
| }, | ||
|
|
||
| // Rule 1 & Rule 2: $defs is restricted strictly to surfaceProperties, anyComponent, and anyFunction. |
There was a problem hiding this comment.
Are the "Rule 1 & Rule 2" callouts adding anything to this doc? And are they actually still pointing to the right rules? I'm wondering if saying the rule number just adds maintenance overhead and confusion or if they're actually helpful.
There was a problem hiding this comment.
Good point — the rule numbers were just adding maintenance overhead and potential confusion. I've removed all // Rule X: and // Rule X & Rule Y: numbering prefixes from the comments in the JSONC schema example in a2ui_protocol.md, leaving only the descriptive explanations.
- Fully remove the Surface Properties section from a2ui_protocol.md - Remove 'Rule X:' number prefixes from comments in the JSONC schema template in a2ui_protocol.md to reduce maintenance overhead and improve clarity
3 participants
Summary
Removes
surfacePropertiesfrom the A2UI v1.0 protocol specification, catalog definitions, and documentation, cleanly separating component layout from branding.Changes
catalog_definition.json,catalogs/basic/catalog.json,test/testing_catalog.json): RemovedsurfacePropertiesschema definitions from$defs.agent_to_renderer.json): Removed thesurfacePropertiesproperty fromCreateSurfaceMessage.a2ui_protocol.md,evolution_guide.md): Removed all references, examples, and descriptions ofsurfaceProperties. Updated the evolution guide to indicate thatthemeandprimaryColorwere removed rather than replaced.eval/src/types.ts,eval/src/validator.ts): RemovedsurfacePropertiesfromCatalogSchemaand from the allowed properties invalidateCreateSurface.surface_properties_validation.jsonand verified all 134 remaining v1.0 specification test cases pass cleanly.CODING_AGENT_LOG.md): Updated activity log with completed tasks and test results.Closes #2126
TAG=agy
CONV=564f1e1b-9755-4c91-a59a-e77c8c281834