docs: clarify createSurface is an error for existing surfaces#1238
docs: clarify createSurface is an error for existing surfaces#1238jacobsimionato wants to merge 1 commit intogoogle:mainfrom
Conversation
There was a problem hiding this comment.
Code Review
This pull request updates the A2UI protocol documentation and JSON schemas for versions 0.9 and 0.10 to explicitly state that sending a 'createSurface' message for an existing 'surfaceId' is an error. Review feedback focuses on ensuring consistency by using 'MUST' instead of 'SHOULD' for error handling in the renderer guide and aligning the JSON descriptions with the markdown documentation's phrasing and formatting.
| 3. The **Transport Layer** (e.g., A2A, MCP) calls `getClientDataModel()` before sending any message to the server. | ||
| 4. If a non-empty data model map is returned, it is included in the transport's metadata field (e.g., `a2uiClientDataModel` in A2A metadata). | ||
|
|
||
| * **Surface Lifecycle**: It is an error to receive a `createSurface` message for a `surfaceId` that is already active. The processor SHOULD throw an error or report a validation failure if this occurs. |
There was a problem hiding this comment.
The use of "SHOULD" here is inconsistent with the protocol specification, which defines sending createSurface for an existing surface as a hard error. To ensure protocol compliance and consistency across implementations, this should be a "MUST" requirement, matching the adjacent "Component Lifecycle" rule.
| * **Surface Lifecycle**: It is an error to receive a `createSurface` message for a `surfaceId` that is already active. The processor SHOULD throw an error or report a validation failure if this occurs. | |
| * **Surface Lifecycle**: It is an error to receive a `createSurface` message for a `surfaceId` that is already active. The processor MUST throw an error or report a validation failure if this occurs. |
There was a problem hiding this comment.
Sounds good--unless there is a deliberate reason to prefer SHOULD I am unaware of.
| "createSurface": { | ||
| "type": "object", | ||
| "description": "Signals the client to create a new surface and begin rendering it. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", | ||
| "description": "Signals the client to create a new surface and begin rendering it. It is an error to send createSurface for a surfaceId that already exists. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", |
There was a problem hiding this comment.
For consistency with the rest of the description and the markdown documentation, the message name createSurface should be enclosed in single quotes. Additionally, adding "without first deleting it" aligns the JSON description with the explicit wording used in the protocol documentation.
| "description": "Signals the client to create a new surface and begin rendering it. It is an error to send createSurface for a surfaceId that already exists. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", | |
| "description": "Signals the client to create a new surface and begin rendering it. It is an error to send 'createSurface' for a surfaceId that already exists without first deleting it. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", |
| "createSurface": { | ||
| "type": "object", | ||
| "description": "Signals the client to create a new surface and begin rendering it. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", | ||
| "description": "Signals the client to create a new surface and begin rendering it. It is an error to send createSurface for a surfaceId that already exists. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", |
There was a problem hiding this comment.
For consistency with the rest of the description and the markdown documentation, the message name createSurface should be enclosed in single quotes. Additionally, adding "without first deleting it" aligns the JSON description with the explicit wording used in the protocol documentation.
| "description": "Signals the client to create a new surface and begin rendering it. It is an error to send createSurface for a surfaceId that already exists. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", | |
| "description": "Signals the client to create a new surface and begin rendering it. It is an error to send 'createSurface' for a surfaceId that already exists without first deleting it. When this message is sent, the client will expect 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId that define the component tree.", |
ditman
left a comment
There was a problem hiding this comment.
Thanks for the clarification here. (I think some of the gemini comments are valid, e.g. SHOULD vs MUST)
Description of Changes
specification/v0_9/docs/a2ui_protocol.mdandspecification/v0_10/docs/a2ui_protocol.mdto state that sendingcreateSurfacefor an existingsurfaceIdis an error.specification/v0_9/json/server_to_client.jsonandspecification/v0_10/json/server_to_client.jsonschemas with the same clarification in thecreateSurfacedescription.specification/v0_9/docs/renderer_guide.mdadvising renderer implementations to handle duplicatecreateSurfacemessages as errors.Rationale
The A2UI specification intended for
createSurfaceto be a one-time initialization per surface. Re-creating a surface without deleting it first leads to ambiguous state in renderers. This change codifies that behavior as an error to ensure protocol consistency across different agent and renderer implementations.Testing/Running Instructions
Review the updated documentation and JSON schema files to ensure the language is clear and consistent with existing protocol documentation.
specification/v0_9/docs/a2ui_protocol.mdspecification/v0_10/docs/a2ui_protocol.mdspecification/v0_9/json/server_to_client.jsonspecification/v0_10/json/server_to_client.jsonspecification/v0_9/docs/renderer_guide.md