Simplify server-side validation of A2UI messages by adding ChildId to explicitly mark component references

[jacobsimionato]

This PR introduces a dedicated ChildId type to the common_types.json schema and updates the standard catalog and documentation to use it. It also completely removes the redundant id type definition, replacing all references with ChildId.

Rationale

In A2UI v0.9, validating referential integrity (ensuring that a component's child or trigger property points to a valid ID in the same surface) currently relies on heuristics. A validator has to "guess" which fields represent IDs based on naming conventions (e.g., checking if a property is named child, children, content, or trigger).

This approach is brittle, especially for Custom Catalogs, where a developer might introduce a new component (e.g., SplitView) with properties like leftPane and rightPane. A generic validator would not know these are structural links that need to be checked.

The Fix

We introduce a semantic marker type in common_types.json:

"ChildId": {
  "type": "string",
  "description": "The unique identifier for a component, used for both definitions and references within the same surface."
}

We then update the standard catalog, the definition of ChildList, and ComponentCommon to explicitly $ref this type. This ensures that every id property and every property that refers to an id is explicitly typed.

Validator Logic (Hypothetical)

With this change, a validator can be implemented deterministically without hardcoded property names. It simply inspects the resolved schema for each property:

# Pseudocode for a robust validator
def validate_component(component, schema):
    for prop, value in component.items():
        prop_schema = resolve_schema(prop, schema)
        
        # Check if this property is structurally defined as an ID Reference
        if prop_schema[''] == 'common_types.json#//ChildId':
            if value not in known_surface_ids:
                raise ValidationError(f"Dangling reference: Component '{value}' not found.")

This ensures that any component in any catalog (standard or custom) that uses these types will automatically benefit from referential integrity checks.

[gemini-code-assist]

Code Review

This pull request introduces a ComponentIdRef type to explicitly mark component ID references within the A2UI JSON schema. This is a valuable change that improves the schema's clarity and simplifies server-side validation by making it easier to identify and check structural links in the UI tree. The changes are applied consistently across the common types and the standard component catalog, and the documentation is updated to reflect this new requirement. Overall, this is a solid improvement for the protocol's robustness. I have one minor suggestion to further enhance validation.

[gemini-code-assist]

To improve schema validation, consider adding "minLength": 1 to this definition. This would prevent empty strings from being considered valid component ID references, which is likely the intended behavior. For consistency, the same constraint could be applied to the main id definition as well.

    "ComponentIdRef": {
      "type": "string",
      "description": "A reference to the unique ID of another component within the same surface.",
      "minLength": 1
    },

[gspencergoog]

Shouldn't this PR remove the id type, since it's no longer used? Theid was meant to serve a similar purpose, with perhaps a too-generic name.

[jacobsimionato]

Oh yes! Ummm sorry I was vibecoding too freely and missed that there was an ID type already defined right above my new one.

[nan-yu]

Should we be more specific to name it childIdRef?

[jacobsimionato]

How about just ComponentId?

I like the idea of including "Ref" in the name, to imply that it's a validated reference. But I think it's even neater if we can share the same type between declarations and references, in which case a generic name makes more sense.

I think when we write a validator, we can have special cased logic so that it knows that the root id parameter of each Component is a declaration (seeing as this is part of the core A2UI specification), but any other parameters with type ComponentId must be references.

[nan-yu]

Sounds good to me. Thanks!