feat: Support component deletion via component: null #528

jacobsimionato · 2026-01-22T03:47:26Z

Description

This PR introduces a mechanism to explicitly delete components from a surface within the updateComponents message.

Changes

Schema Update: The server_to_client.json schema for updateComponents has been modified. The components list now accepts a 'tombstone' object in addition to standard component definitions.
Tombstone Format: A tombstone is defined as an object with the target component's id and the component property set explicitly to null.
Documentation: Updated a2ui_protocol.md to document this new behavior.
Testing: Added component_deletion.json to the test suite and updated the evaluation framework to support this feature.

Rationale

Previously, removing a component typically required re-sending the entire parent structure or using deleteSurface and recreating it, which is inefficient and can disrupt the user experience. This change allows for granular updates where specific components can be removed while others are added or updated in the same atomic message.

Sample Code

To delete a component with ID loading-spinner and simultaneously add a new status-text component:

{
  "updateComponents": {
    "surfaceId": "main",
    "components": [
      {
        "id": "loading-spinner",
        "component": null
      },
      {
        "id": "status-text",
        "component": "Text",
        "text": "Loaded Successfully"
      }
    ]
  }
}

Update server_to_client.json schema to allow component: null. Update protocol documentation. Add component_deletion.json test cases. Update evaluation framework to support and test this feature.

gemini-code-assist

Code Review

This pull request introduces a valuable feature to support component deletion using a component: null tombstone. The implementation is solid, with corresponding updates to the protocol documentation, JSON schema, and evaluation logic. I have a couple of suggestions to improve the clarity and consistency of the documentation. Additionally, please remember to fill out the Pre-Review Checklist in the pull request description as required by the repository's contribution guidelines.

gemini-code-assist · 2026-01-22T03:49:17Z

specification/v0_9/docs/a2ui_protocol.md

 ### `updateComponents`

-This message provides a list of UI components to be added to or updated within a specific surface. The components are provided as a flat list, and their relationships are defined by ID references in an adjacency list. This message may only be sent to a surface that has already been created. Note that components may reference children or data bindings that do not yet exist; clients should handle this gracefully by rendering placeholders (progressive rendering).
+This message provides a list of UI components to be added, updated, or removed within a specific surface. The components are provided as a flat list, and their relationships are defined by ID references in an adjacency list. This message may only be sent to a surface that has already been created.


The previous version of this paragraph included an important note about progressive rendering: "Note that components may reference children or data bindings that do not yet exist; clients should handle this gracefully by rendering placeholders (progressive rendering)."

While this concept is mentioned elsewhere in the documentation, it is highly relevant in the updateComponents section. Its removal could cause confusion for developers implementing a client. I recommend re-adding a concise version of this note to ensure client implementation details are clear in this context.

Yes, we should keep the part describing progressive rendering.

gemini-code-assist · 2026-01-22T03:49:17Z

specification/v0_9/docs/a2ui_protocol.md

      {
-        "id": "user_title",
-        "component": "Text",
-        "text": "Software Engineer"
+        "id": "old_component_id",
+        "component": null
      }


The updated example is a bit confusing. The root component (defined on lines 172-174) references a component with id: "user_title" in its children array. However, this change removes the user_title component and replaces it with a deletion request for old_component_id. This leaves a dangling reference in root and it's not clear what old_component_id refers to.

To make the example clearer and self-consistent, I recommend showing the deletion of an existing component from the example, like user_title. You would also need to update the root component to remove user_title from its children array for a fully consistent state.

Here is a suggestion to make the intent clearer, though the root component would still need to be updated separately.

Suggested change

{

"id": "user_title",

"component": "Text",

"text": "Software Engineer"

"id": "old_component_id",

"component": null

}

"id": "user_title",

"component": null

This is a valid issue don't remove user_title: it's referenced.

Sounds good. Can you update the example so that it actions this feedback by reinstating user_title, then adding a second json block that includes messages to update the root component to remove the reference to user_title, and then delete user_title?

jacobsimionato · 2026-01-22T03:49:23Z

This addresses #235

wrenj · 2026-01-22T10:09:08Z

specification/v0_9/docs/a2ui_protocol.md

-        "component": "Text",
-        "text": "Software Engineer"
+        "id": "old_component_id",
+        "component": null


why wouldn't it work to just exclude component?

{
"id": "old_component_id"
}

updateDataModel overwrites instead of merging, and it treats null as remove key, so it should have the same effect, no?

Oh that's a great idea! Let's make the "component" property optional, but include description for that property that makes it clear that it should only be omitted to indicate deleting an existing component. I think I should run an eval on that too to make sure that removing the "required" aspect does confuse LLMs too much.

gspencergoog · 2026-01-22T17:08:07Z

How do we expect this to be used? Will we be prompting the LLM to do garbage collection? Wouldn't it be more effective to just have a message from the LLM to the client that it believes all relevant components are being referenced, and the client is free to do garbage collection? I have doubts that the LLM will be able (or have the information to) keep track of all component references.

gspencergoog · 2026-01-22T17:03:31Z

specification/v0_9/docs/a2ui_protocol.md

 ### `updateComponents`

-This message provides a list of UI components to be added to or updated within a specific surface. The components are provided as a flat list, and their relationships are defined by ID references in an adjacency list. This message may only be sent to a surface that has already been created. Note that components may reference children or data bindings that do not yet exist; clients should handle this gracefully by rendering placeholders (progressive rendering).
+This message provides a list of UI components to be added, updated, or removed within a specific surface. The components are provided as a flat list, and their relationships are defined by ID references in an adjacency list. This message may only be sent to a surface that has already been created.


Yes, we should keep the part describing progressive rendering.

gspencergoog · 2026-01-22T17:04:24Z

specification/v0_9/docs/a2ui_protocol.md


 - `surfaceId` (string, required): The unique identifier for the UI surface to be updated. This is typically a name with meaning (e.g. "user_profile_card"), and it has to be unique within the context of the GenUI session.
- `components` (array, required): A list of component objects. The components are provided as a flat list, and their relationships are defined by ID references in an adjacency list.
+- `components` (array, required): A list of component objects (for updates) or tombstone objects (for deletions).


What about the adjacency list description? I think we should keep that.

Oh yes, let's reinstate that sorry!

gspencergoog · 2026-01-22T17:05:15Z

specification/v0_9/docs/a2ui_protocol.md

      {
-        "id": "user_title",
-        "component": "Text",
-        "text": "Software Engineer"
+        "id": "old_component_id",
+        "component": null
      }


This is a valid issue don't remove user_title: it's referenced.

jacobsimionato · 2026-01-29T11:36:46Z

I have addressed the feedback. Please take another look.

jacobsimionato · 2026-01-29T11:36:58Z

/gemini review

gemini-code-assist

Code Review

This pull request introduces a useful feature for deleting components via updateComponents. The implementation is mostly solid, with updates to the schema, documentation, and new tests.

However, there's a significant inconsistency between how component deletion is described in the pull request title/description (component: null) and how it's actually implemented and documented in the code (omitting the component property). My review comments focus on resolving this inconsistency to ensure the feature is clear, correct, and maintainable.

I've also suggested tightening the validation logic and adding a test case to make the contract for deletion explicit.

Additionally, I noticed some unrelated but correct fixes to the action property in several test files. While it's better to keep PRs focused on a single feature, these changes are valid.

gemini-code-assist · 2026-01-29T11:38:15Z

specification/v0_9/docs/a2ui_protocol.md

+To add or update a component, provide the full component definition object. If a component with the same `id` already exists, it will be replaced.
+
+**Deleting Components:**
+To delete a component, provide an object with the component's `id` and omit the `component` property. This removes the component from the client's memory.


This documentation correctly states that deletion is done by omitting the component property, which aligns with the JSON schema. However, the pull request title (feat: Support component deletion via component: null) and description are inconsistent with this, as they state deletion is done via component: null. Please update the PR title and description to match the implemented behavior to avoid confusion.

gemini-code-assist · 2026-01-29T11:38:15Z

specification/v0_9/eval/src/validator.ts

+    if (componentType === undefined || componentType === null) {
+      return;
+    }


This check is more permissive than what the JSON schema allows. The schema (server_to_client.json) defines a tombstone for deletion as an object with only an id property, enforced by additionalProperties: false. This means a payload with component: null would fail schema validation before this custom validation code is even reached. To avoid confusion and align strictly with the schema, this check should only allow for an omitted component property.

Suggested change

if (componentType === undefined || componentType === null) {

return;

}

if (componentType === undefined) {

// This is a tombstone for component deletion, which is valid per the schema.

return;

}

gemini-code-assist · 2026-01-29T11:38:15Z

specification/v0_9/test/cases/component_deletion.json

+          ]
+        }
+      }
+    }


These test cases are great for verifying the deletion-by-omission behavior. To make the contract even more explicit and prevent future regressions, it would be beneficial to add a test case that asserts that using component: null is invalid, as per the current JSON schema. This would help solidify that only omitting the component property is the supported method for deletion.

}, { "description": "Deletion with component: null (should be invalid per schema)", "valid": false, "data": { "updateComponents": { "surfaceId": "test_surface", "components": [ { "id": "item_to_delete", "component": null } ] } } }

feat: Support component deletion via component: null

40c7756

Update server_to_client.json schema to allow component: null. Update protocol documentation. Add component_deletion.json test cases. Update evaluation framework to support and test this feature.

github-project-automation bot added this to A2UI Jan 22, 2026

github-project-automation bot moved this to Todo in A2UI Jan 22, 2026

gemini-code-assist bot reviewed Jan 22, 2026

View reviewed changes

jacobsimionato requested review from gspencergoog and wrenj January 22, 2026 03:49

wrenj reviewed Jan 22, 2026

View reviewed changes

gspencergoog reviewed Jan 22, 2026

View reviewed changes

fix: Address PR feedback

706868a

gemini-code-assist bot reviewed Jan 29, 2026

View reviewed changes

jacobsimionato requested review from gspencergoog and wrenj January 29, 2026 11:38

-    if (componentType === undefined || componentType === null) {
-      return;
-    }
+    if (componentType === undefined) {
+      // This is a tombstone for component deletion, which is valid per the schema.
+      return;
+    }

feat: Support component deletion via component: null #528

Are you sure you want to change the base?

feat: Support component deletion via component: null #528

Uh oh!

Conversation

jacobsimionato commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Rationale

Sample Code

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobsimionato commented Jan 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gspencergoog commented Jan 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobsimionato commented Jan 29, 2026

Uh oh!

jacobsimionato commented Jan 29, 2026

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jacobsimionato commented Jan 22, 2026 •

edited

Loading