Repository navigation
[v1.0][core] Implement metadata accessor and change notification APIs (getMetadata, setMetadata, onMetadataChanged) #3708
Description
Summary
The v1.0 protocol specification defines an SDK accessor pattern for surface and component metadata (metadata.extensions) in specification/v1_0/docs/a2ui_protocol.md (introduced in PR #2187):
getMetadata()retrieves the metadata object containing extensions.setMetadata(metadata)updates the metadata object and notifies listeners.onMetadataChanged(callback)registers a callback that fires whenever metadata updates.
None of the core SDKs (TypeScript, Dart, Python, or Swift) or blueprints (a2ui_core.blueprint.md, node_resolution.blueprint.md) implement these metadata APIs.
Current state across SDKs
- In TypeScript (
@a2ui/web_core),SurfaceModel.metadatais a read-only field initialized atcreateSurface, andComponentModel.metadatais a plain mutable field.MessageProcessor.applyComponentUpdateassignsexisting.metadatabeforeexisting.properties, which firesComponentModel.onUpdated. Direct mutations tocomponentModel.metadatado not notify listeners, andComponentNodedoes not expose or observemetadata(see [v1.0][web_core][react] ComponentNode and useNodeView omit component metadata.extensions from resolved nodes and toJSON() #3469). - In Dart (
a2ui_core),SurfaceModel.metadataisfinal, andComponentModel.metadatais a plain mutable field updated beforeComponentModel.onUpdatedinMessageProcessor._applyComponentModels. NeitherSurfaceModel,ComponentModel, norComponentNodeprovidesgetMetadata(),setMetadata(), oronMetadataChanged. - In Python (
a2ui_core), neitherSurfaceModelnorComponentModelextractsmetadataonto a dedicated field or provides metadata accessors and change callbacks.MessageProcessor._process_update_components_opleaves"metadata"insideComponentModel.properties. - In Swift (
A2UICore),SurfaceViewModel.metadatais aletconstant, whileComponentModelhas nometadatafield.MessageProcessor.applyComponentsBatchleaves"metadata"insideproperties.
Expected behavior
- Define the canonical metadata accessor and change notification contract (
getMetadata(),setMetadata(metadata), andonMetadataChanged(callback), or idiomatic reactive equivalents) ina2ui_core.blueprint.mdandnode_resolution.blueprint.md. - Implement the metadata APIs across the TypeScript, Dart, Python, and Swift core SDKs for surface and component extension metadata.
Activity
gspencergoog commentedon Oct 28, 2026
cc @redbrogdon
gspencergoog commentedon Oct 28, 2026
Proposed API Design
This comment outlines the target design for the v1.0 metadata APIs across all SDKs and blueprints.
1. State Layer (
SurfaceModel&ComponentModel)Both
SurfaceModelandComponentModelimplement a unifiedMetadataHoldercontract:getMetadata()returns an immutable snapshot of the currentA2uiMetadata({"extensions": {...}}) orundefined/None/nil.setMetadata(metadata)validates UAX 31 extension namespace keys and deep-copies the input so external mutations cannot change committed state. It updates the stored metadata and emitsonMetadataChangedonly when the value changes by structural equality.onMetadataChangedis anEventSource<A2uiMetadata | undefined>(orStreamin Dart) that fires wheneversetMetadataor an inboundupdateComponentsmessage changes the metadata.MessageProcessorupdates (updateComponents),componentModel.setMetadata(newMetadata)runs independently ofcomponentModel.properties. Metadata-only updates fireonMetadataChangedwithout emitting spuriousonUpdatedevents when component properties are unchanged.2. Resolution & Catalog Layer (
ComponentNode&ComponentApi)Framework adapter views only receive
ComponentNodeandSurfaceModel(and do not accessComponentModeldirectly). To allow views to recover and react to metadata without pollutingComponentNode.props:ComponentNodeexposes a reactivereadonly metadata: Signal<A2uiMetadata | undefined>(orValueListenablein Dart,@Observableproperty in Swift) plus agetMetadata()convenience getter.NodeResolverseedsnode.metadatafromcomponentModel.getMetadata()on node creation and subscribes tocomponentModel.onMetadataChangedto updatenode.metadatain place without re-evaluatingnode.props.ComponentApiexposesreadonly metadata?: A2uiMetadataacross TypeScript, Dart, Python, and Swift so views can recover static catalog definition metadata vianode.impl?.metadata.3. Outbound Action Metadata (Issue #3468)
SurfaceModel.dispatchAction(payload, sourceComponentId, metadata?)andNodeAction(metadata?)accept optional renderer-sideA2uiMetadataand include it on the outboundA2uiRendererActionpayload (action.metadata.extensions).4. Agent-Side Authoring (Builders & Express DSL)
ComponentBuilderNode,CreateSurface,ComponentApi, andA2uiRendererActionacceptmetadata(orextensionsshorthand) at construction time. They also provide.set_metadata(extensions)and.with_extension(namespace, value)helpers that validate UAX 31 extension keys immediately.metadata=andextensions=as reserved envelope keyword arguments onsurface(...)and component calls. If a catalog component explicitly declares a schema property namedmetadata, the compiler routesmetadata=to that property and reservesextensions=for the envelope.🤖 Agent-generated
feat(metadata): implement v1.0 extension metadata APIs across SDKs
feat(metadata): implement v1.0 extension metadata APIs across SDKs
feat(metadata): implement v1.0 extension metadata APIs across SDKs (a…