v1.0 JSON Schemas
A2UI v1.0 defines wire envelopes, shared types, catalog formats, and capability negotiation payloads across 11 canonical JSON Schemas included from specification/v1_0/json/. For the reference component catalog schema, see the v1.0 Basic Catalog Guide. For v0.9.1, see the v0.9.1 JSON Schemas.
Wire messages
agent_to_renderer.json
A2UI Message Schema — Describes a JSON payload for an A2UI message, which is used to dynamically construct and update user interfaces.
Definitions & properties (8)
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/agent_to_renderer.json", "title": "A2UI Message Schema", "description": "Describes a JSON payload for an A2UI message, which is used to dynamically construct and update user interfaces.", "type": "object", "oneOf": [ {"$ref": "#/$defs/CreateSurfaceMessage"}, {"$ref": "#/$defs/UpdateComponentsMessage"}, {"$ref": "#/$defs/UpdateDataModelMessage"}, {"$ref": "#/$defs/DeleteSurfaceMessage"}, {"$ref": "#/$defs/CallRendererFunctionMessage"}, {"$ref": "#/$defs/AgentFunctionResponseMessage"} ], "$defs": { "CreateSurfaceMessage": { "type": "object", "properties": { "version": { "const": "1.0" }, "createSurface": { "type": "object", "description": "Signals the renderer to create a new surface and begin rendering it. Creating a surface implicitly instantiates the canonical 'Surface' container component ('common_types.json#/$defs/Surface') with 'child': 'root'. It is an error to try to create a surface with an existing ID without first deleting it; surfaceId MUST be globally unique for the renderer's lifetime. The component tree and initial data model may be provided inline via 'components' and 'dataModel', or sent later in 'updateComponents' and/or 'updateDataModel' messages for the same surfaceId.", "properties": { "surfaceId": { "type": "string", "description": "The unique identifier for the UI surface to be rendered. It must be globally unique for the renderer's lifetime." }, "catalogId": { "type": "string", "description": "A string that uniquely identifies the default catalog for this surface. It is recommended to prefix this with an internet domain that you own, to avoid conflicts e.g. 'mycompany.com:somecatalog'. Components and function calls that do not explicitly specify a catalogId will use this surface-level default catalogId." }, "sendDataModel": { "type": "boolean", "description": "If true, the renderer will send the full data model of this surface in the metadata of every A2A message sent to the agent that created the surface. Defaults to false." }, "components": { "$ref": "#/$defs/ComponentsList" }, "dataModel": { "type": "object", "description": "The initial root data model object for the surface.", "additionalProperties": true }, "metadata": { "type": "object", "description": "Optional surface-level metadata.", "properties": { "extensions": { "$ref": "common_types.json#/$defs/Extensions" } }, "additionalProperties": false } }, "required": ["surfaceId"], "additionalProperties": false } }, "required": ["createSurface", "version"], "additionalProperties": false }, "Component": { "description": "A UI component for the surface, combining baseline envelope properties with the catalog component definition.", "allOf": [ { "$ref": "common_types.json#/$defs/ComponentCommon" }, { "$ref": "catalog.json#/$defs/anyComponent" }, { "type": "object", "properties": { "component": { "not": { "const": "Surface" } } } } ], "unevaluatedProperties": false }, "ComponentsList": { "type": "array", "description": "A list containing UI components for the surface.", "minItems": 1, "items": { "$ref": "#/$defs/Component" } }, "UpdateComponentsMessage": { "type": "object", "properties": { "version": { "const": "1.0" }, "updateComponents": { "type": "object", "description": "Updates a surface with a new set of components. This message can be sent multiple times to update the component tree of an existing surface. One of the components in one of the components lists MUST have an 'id' of 'root' to serve as the root of the component tree. The createSurface message MUST have been previously sent for this surfaceId.", "properties": { "surfaceId": { "type": "string", "description": "The unique identifier for the UI surface to be updated. It must be globally unique for the renderer's lifetime." }, "components": { "$ref": "#/$defs/ComponentsList" } }, "required": ["surfaceId", "components"], "additionalProperties": false } }, "required": ["updateComponents", "version"], "additionalProperties": false }, "UpdateDataModelMessage": { "type": "object", "properties": { "version": { "const": "1.0" }, "updateDataModel": { "type": "object", "description": "Updates the data model for an existing surface. This message can be sent multiple times to update the data model. The createSurface message MUST have been previously sent for this surfaceId.", "properties": { "surfaceId": { "type": "string", "description": "The unique identifier for the UI surface this data model update applies to. It must be globally unique for the renderer's lifetime." }, "path": { "type": "string", "description": "An optional path to a location within the data model (e.g., '/user/name'). If omitted, or set to '/', refers to the entire data model." }, "value": { "description": "The data to be updated in the data model. To delete the key/value at 'path', set 'value' explicitly to null." } }, "required": ["surfaceId", "value"], "additionalProperties": false } }, "required": ["updateDataModel", "version"], "additionalProperties": false }, "DeleteSurfaceMessage": { "type": "object", "properties": { "version": { "const": "1.0" }, "deleteSurface": { "type": "object", "description": "Signals the renderer to delete the surface identified by 'surfaceId'. The createSurface message MUST have been previously sent for this surfaceId.", "properties": { "surfaceId": { "type": "string", "description": "The unique identifier for the UI surface to be deleted. It must be globally unique for the renderer's lifetime." } }, "required": ["surfaceId"], "additionalProperties": false } }, "required": ["deleteSurface", "version"], "additionalProperties": false }, "CallRendererFunctionMessage": { "type": "object", "properties": { "version": { "const": "1.0" }, "callRendererFunction": { "type": "object", "description": "Signals the renderer to execute a function locally on behalf of the agent.", "properties": { "surfaceId": { "type": "string", "description": "Optional ID of the surface whose data model provides the evaluation context for this call. If omitted, the function executes in a surface-independent root context with an empty data model." }, "functionCallId": { "$ref": "common_types.json#/$defs/CallId", "description": "Unique ID for this instance of the function call. The renderer MUST copy this ID into the return response." }, "callFunction": { "allOf": [ { "$ref": "common_types.json#/$defs/FunctionCall" }, { "required": ["catalogId"] } ] } }, "required": ["functionCallId", "callFunction"], "additionalProperties": false } }, "required": ["callRendererFunction", "version"], "additionalProperties": false }, "AgentFunctionResponseMessage": { "type": "object", "properties": { "version": { "const": "1.0" }, "agentFunctionResponse": { "$ref": "common_types.json#/$defs/FunctionResponse" } }, "required": ["agentFunctionResponse", "version"], "additionalProperties": false } }}renderer_to_agent.json
A2UI Renderer-to-Agent Event Schema — Describes a JSON payload for a renderer-to-agent event message.
Definitions & properties (5)
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/renderer_to_agent.json", "title": "A2UI Renderer-to-Agent Event Schema", "description": "Describes a JSON payload for a renderer-to-agent event message.", "type": "object", "minProperties": 2, "maxProperties": 2, "properties": { "version": { "const": "1.0" }, "action": { "type": "object", "description": "Reports a user-initiated action from a component.", "properties": { "name": { "type": "string", "description": "The name of the action, taken from the component's action.event.name property." }, "userMessage": { "type": "string", "description": "An optional human-readable string describing the action performed by the user, taken from the component's action.event.userMessage property after resolving bindings." }, "surfaceId": { "type": "string", "description": "The id of the surface where the event originated. It must be globally unique for the renderer's lifetime." }, "sourceComponentId": { "type": "string", "description": "The id of the component that triggered the event." }, "timestamp": { "type": "string", "format": "date-time", "description": "An ISO 8601 timestamp of when the event occurred." }, "context": { "type": "object", "description": "A JSON object containing the key-value pairs from the component's action.event.context, after resolving all data bindings.", "additionalProperties": true }, "metadata": { "type": "object", "description": "Optional renderer-side metadata to send back to the agent with the action.", "properties": { "extensions": { "$ref": "common_types.json#/$defs/Extensions" } }, "additionalProperties": false } }, "required": ["name", "surfaceId", "sourceComponentId", "timestamp", "context"] }, "callAgentFunction": { "type": "object", "description": "Signals the agent to execute a function remotely on behalf of the renderer.", "properties": { "surfaceId": { "type": "string", "description": "The surface ID where the call originated." }, "functionCallId": { "$ref": "common_types.json#/$defs/CallId", "description": "Unique ID for this instance of the function call. The agent MUST copy this ID into the return response." }, "callFunction": { "$ref": "common_types.json#/$defs/FunctionCall" } }, "required": ["surfaceId", "functionCallId", "callFunction"], "additionalProperties": false }, "rendererFunctionResponse": { "$ref": "common_types.json#/$defs/FunctionResponse" }, "error": { "description": "Reports a renderer-side error.", "oneOf": [ { "type": "object", "title": "Validation Failed Error", "properties": { "code": { "enum": ["VALIDATION_FAILED", "UNALLOWED_PARENT", "UNALLOWED_CHILD"] }, "surfaceId": { "type": "string", "description": "The id of the surface where the error occurred. It must be globally unique for the renderer's lifetime." }, "path": { "type": "string", "description": "The JSON pointer to the field that failed validation (e.g. '/components/0/text')." }, "message": { "type": "string", "description": "A short one or two sentence description of why validation failed." } }, "required": ["code", "path", "message", "surfaceId"], "additionalProperties": false }, { "type": "object", "title": "Generic Error", "properties": { "code": { "type": "string", "not": { "enum": ["VALIDATION_FAILED", "UNALLOWED_PARENT", "UNALLOWED_CHILD"] } }, "message": { "type": "string", "description": "A short one or two sentence description of why the error occurred." }, "surfaceId": { "type": "string", "description": "The id of the surface where the error occurred. It must be globally unique for the renderer's lifetime." }, "functionCallId": { "$ref": "common_types.json#/$defs/CallId", "description": "The unique ID of the function invocation, which must be identical to the value specified in the function invocation." } }, "required": ["code", "message"], "oneOf": [ { "required": ["surfaceId"], "not": { "required": ["functionCallId"] } }, { "required": ["functionCallId"], "not": { "required": ["surfaceId"] } } ], "additionalProperties": true } ] } }, "oneOf": [ { "required": ["action", "version"] }, { "required": ["callAgentFunction", "version"] }, { "required": ["rendererFunctionResponse", "version"] }, { "required": ["error", "version"] } ]}Common types
common_types.json
A2UI Common Types — Common type definitions used across A2UI schemas.
Definitions & properties (21)
Definitions ($defs):
ComponentId, CallId, AccessibilityAttributes, Extensions, ComponentCommon, Child, ChildList, DataBinding, DynamicValue, DynamicString, DynamicNumber, DynamicBoolean, DynamicStringList, FunctionCommon, IndexSystemFunction, FunctionCall, CheckRule, Checkable, Action, Surface, FunctionResponse{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/common_types.json", "title": "A2UI Common Types", "description": "Common type definitions used across A2UI schemas.", "$defs": { "ComponentId": { "type": "string", "description": "The unique identifier for a component, used for both definitions and references within the same surface." }, "CallId": { "type": "string", "description": "The unique identifier for a function call." }, "AccessibilityAttributes": { "type": "object", "description": "Attributes to enhance accessibility when using assistive technologies like screen readers or model understanding.", "properties": { "label": { "$ref": "#/$defs/DynamicString", "description": "A short string, typically 1 to 3 words, used by assistive technologies to convey the purpose or intent of an element. For example, an input field might have an accessible label of 'User ID' or a button might be labeled 'Submit'." }, "description": { "$ref": "#/$defs/DynamicString", "description": "Additional information provided by assistive technologies about an element such as instructions, format requirements, or result of an action. For example, a mute button might have a label of 'Mute' and a description of 'Silences notifications about this conversation'." }, "live": { "type": "string", "description": "Controls screen reader announcements for dynamic updates (WAI-ARIA aria-live). 'polite' waits for user pause; 'assertive' interrupts immediately for alerts.", "enum": ["off", "polite", "assertive"], "default": "off" }, "hidden": { "$ref": "#/$defs/DynamicBoolean", "description": "Hides the element and its children from assistive technologies when true. Default is false." } }, "additionalProperties": false }, "Extensions": { "type": "object", "description": "Optional extension metadata. Keys MUST be Unicode identifiers (UAX #31). Keys starting with 'a2ui_' are reserved for official extensions.", "patternProperties": { "^[\\p{XID_Start}_][\\p{XID_Continue}]*$": {} }, "additionalProperties": false }, "ComponentCommon": { "type": "object", "properties": { "id": { "$ref": "#/$defs/ComponentId" }, "catalogId": { "type": "string", "description": "The catalog ID for this component, overriding any surface-level default catalogId." }, "accessibility": { "$ref": "#/$defs/AccessibilityAttributes" }, "metadata": { "type": "object", "description": "Optional component-level metadata for vendor extensions.", "properties": { "extensions": { "$ref": "#/$defs/Extensions" } }, "additionalProperties": false } }, "required": ["id"] }, "Child": { "$ref": "#/$defs/ComponentId", "description": "A reference to a single child component ID." }, "ChildList": { "oneOf": [ { "type": "array", "description": "A static list of child component IDs.", "items": { "$ref": "#/$defs/ComponentId" } }, { "type": "object", "description": "A template for generating a dynamic list of children from a data model list. The `componentId` is the component to use as a template.", "properties": { "componentId": { "$ref": "#/$defs/ComponentId" }, "path": { "type": "string", "description": "The path to the list of component property objects in the data model." } }, "required": ["componentId", "path"], "additionalProperties": false } ] }, "DataBinding": { "type": "object", "properties": { "@path": { "type": "string", "description": "A JSON Pointer path to a value in the data model." } }, "required": ["@path"], "additionalProperties": false }, "DynamicValue": { "description": "A value that can be a literal, a path, or a function call returning any type.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array" }, { "type": "object", "propertyNames": { "not": { "pattern": "^@([^@]|$)" } }, "not": { "anyOf": [ { "required": ["@path"] }, { "required": ["@call"] } ] } }, { "$ref": "#/$defs/DataBinding" }, { "$ref": "#/$defs/FunctionCall" } ] }, "DynamicString": { "description": "Represents a string", "oneOf": [ { "type": "string" }, { "$ref": "#/$defs/DataBinding" }, { "$ref": "#/$defs/FunctionCall" } ] }, "DynamicNumber": { "description": "Represents a value that can be either a literal number, a path to a number in the data model, or a function call returning a number.", "oneOf": [ { "type": "number" }, { "$ref": "#/$defs/DataBinding" }, { "$ref": "#/$defs/FunctionCall" } ] }, "DynamicBoolean": { "description": "A boolean value that can be a literal, a path, or a function call returning a boolean or a validation result object (coerced to its 'valid' boolean).", "oneOf": [ { "type": "boolean" }, { "$ref": "#/$defs/DataBinding" }, { "$ref": "#/$defs/FunctionCall" } ] }, "DynamicStringList": { "description": "Represents a value that can be either a literal array of strings, a path to a string array in the data model, or a function call returning a string array.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "$ref": "#/$defs/DataBinding" }, { "$ref": "#/$defs/FunctionCall" } ] }, "FunctionCommon": { "type": "object", "description": "Baseline envelope properties common to all function calls. Function-specific argument schemas ('args') are defined individually by each function in the active catalog.", "properties": { "@call": { "type": "string", "description": "The name of the function to call." }, "catalogId": { "type": "string", "description": "The catalog ID for this function, overriding any surface-level default catalogId." } }, "required": ["@call"] }, "IndexSystemFunction": { "type": "object", "description": "Returns the 0-based index of the current item when rendering a dynamic list from a template. This function MUST ONLY be available when evaluating template items within a list context.", "properties": { "@call": { "const": "@index" }, "args": { "type": "object", "properties": { "offset": { "$ref": "#/$defs/DynamicNumber", "description": "Optional. An offset to add to the 0-based index (e.g., 1 for 1-based indexing). Defaults to 0.", "default": 0 } }, "unevaluatedProperties": false } }, "required": ["@call"], "unevaluatedProperties": false, "returnType": "number" }, "FunctionCall": { "type": "object", "description": "Invokes a named function, combining common function properties with the catalog function definition.", "allOf": [ { "$ref": "#/$defs/FunctionCommon" }, { "oneOf": [ { "$ref": "catalog.json#/$defs/anyFunction" }, { "$ref": "#/$defs/IndexSystemFunction" } ] } ], "unevaluatedProperties": false }, "CheckRule": { "type": "object", "description": "A single validation check rule applied to an input component. The condition function or path evaluates to a structured validation result object or a boolean (which is coerced to a validation result object).", "properties": { "condition": { "description": "Path or function call evaluating to a structured validation result object or a boolean.", "oneOf": [{"$ref": "#/$defs/DataBinding"}, {"$ref": "#/$defs/FunctionCall"}] }, "message": { "type": "string", "description": "Optional fallback error message." } }, "required": ["condition"], "additionalProperties": false }, "Checkable": { "type": "object", "description": "Properties for components that support renderer-side checks.", "properties": { "checks": { "type": "array", "description": "A list of validation check rules to perform on the component.", "items": { "$ref": "#/$defs/CheckRule" } } } }, "Action": { "description": "Defines an interaction handler that can either trigger an agent-side event or execute a local renderer-side function.", "oneOf": [ { "type": "object", "description": "Triggers an agent-side event.", "properties": { "event": { "type": "object", "description": "The event to dispatch to the agent.", "properties": { "name": { "type": "string", "description": "The name of the action to be dispatched to the agent." }, "userMessage": { "$ref": "#/$defs/DynamicString", "description": "An optional human-readable message describing the action performed by the user, resolved by the renderer and included in the outbound action message." }, "context": { "type": "object", "description": "A JSON object containing the key-value pairs for the action context. Values can be literals or paths. Use literal values unless the value must be dynamically bound to the data model. Do NOT use paths for static IDs.", "additionalProperties": { "$ref": "#/$defs/DynamicValue" } } }, "required": ["name"], "additionalProperties": false } }, "required": ["event"], "additionalProperties": false }, { "type": "object", "description": "Executes a renderer or agent-side function.", "properties": { "functionCall": { "$ref": "#/$defs/FunctionCall" } }, "required": ["functionCall"], "additionalProperties": false } ] }, "Surface": { "title": "Surface Container Component", "description": "The reserved canonical container component representing an A2UI surface. The Surface component is immutable and always has 'child': 'root'.", "type": "object", "allowedParents": [], "properties": { "component": { "const": "Surface" }, "child": { "const": "root" } }, "additionalProperties": false }, "FunctionResponse": { "type": "object", "description": "The return response matching a callAgentFunction or callRendererFunction invocation.", "properties": { "functionCallId": { "$ref": "#/$defs/CallId", "description": "The unique ID matching the initiating function call." }, "value": { "description": "The return value of the function." }, "error": { "type": "object", "description": "An error object indicating failure of the function execution.", "properties": { "code": {"type": "string"}, "message": {"type": "string"} }, "required": ["code", "message"], "additionalProperties": false } }, "required": ["functionCallId"], "oneOf": [{"required": ["value"]}, {"required": ["error"]}], "additionalProperties": false } }}Catalog definition and data model
catalog_definition.json
A2UI Catalog Definition Schema — A collection of component and function definitions.
Definitions & properties (16)
Definitions ($defs):
FunctionCallValidationSchema, FunctionDefinition, LeafDefinition, ComponentDefinition, ValidationResultProperties:
$schema, $id, protocolVersion, $defs, title, description, catalogId, metadata, instructions, components, functions{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/catalog_definition.json", "title": "A2UI Catalog Definition Schema", "description": "A collection of component and function definitions.", "type": "object", "properties": { "$schema": {"type": "string"}, "$id": {"type": "string"}, "protocolVersion": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:\\.(0|[1-9][0-9]*))?(?:-((?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", "default": "0.9", "description": "The A2UI specification version of this catalog definition (e.g. '1.0'). Defaults to '0.9' if omitted." }, "$defs": { "type": "object", "description": "Standardized schema definitions referenced from outside the catalog file, and custom leaf definitions.", "properties": { "anyComponent": { "title": "A2UI Any Component Schema", "description": "Unified validation schema for all components.", "$ref": "https://json-schema.org/draft/2020-12/schema" }, "anyFunction": { "title": "A2UI Any Function Schema", "description": "Unified validation schema for all functions.", "$ref": "https://json-schema.org/draft/2020-12/schema" } }, "required": ["anyComponent", "anyFunction"], "additionalProperties": { "$ref": "#/$defs/LeafDefinition" } }, "title": { "type": "string", "description": "The title of the catalog." }, "description": { "type": "string", "description": "A human-readable description of the catalog." }, "catalogId": { "type": "string", "description": "Unique identifier for this catalog." }, "metadata": { "type": "object", "description": "Optional catalog-level metadata.", "properties": { "extensions": { "$ref": "common_types.json#/$defs/Extensions" } }, "additionalProperties": false }, "instructions": { "type": "string", "description": "Markdown-formatted design guidelines or instructions specific to this catalog." }, "components": { "type": "object", "description": "Definitions for UI components supported by this catalog.", "propertyNames": { "not": { "const": "Surface" } }, "additionalProperties": { "$ref": "#/$defs/ComponentDefinition" } }, "functions": { "type": "object", "description": "Definitions for functions supported by this catalog.", "additionalProperties": { "$ref": "#/$defs/FunctionDefinition" } } }, "required": ["catalogId"], "additionalProperties": false, "$defs": { "FunctionCallValidationSchema": { "type": "object", "description": "JSON Schema structure that validates a wire-level FunctionCall object.", "properties": { "type": { "const": "object" }, "description": { "type": "string" }, "properties": { "type": "object", "properties": { "@call": { "type": "object", "properties": { "const": {"type": "string"} }, "required": ["const"] }, "args": { "type": "object", "description": "A JSON Schema describing the expected arguments (args) for this function.", "$ref": "https://json-schema.org/draft/2020-12/schema" } }, "required": ["@call"], "additionalProperties": false }, "required": { "type": "array", "items": {"type": "string"}, "contains": {"const": "@call"} } }, "required": ["type", "properties", "required"] }, "FunctionDefinition": { "type": "object", "description": "Describes a function's validation schema and interface metadata.", "allOf": [ { "$ref": "#/$defs/FunctionCallValidationSchema" }, { "type": "object", "properties": { "returnType": { "type": "string", "enum": [ "string", "number", "boolean", "array", "object", "validationResult", "any", "void" ], "description": "The type of value this function returns." }, "allowedCallers": { "type": "string", "enum": ["rendererOnly", "agentOnly", "rendererOrAgent"], "default": "rendererOnly", "description": "Specifies which roles are authorized to invoke this function." }, "requiresUserActivation": { "type": "boolean", "default": false, "description": "Specifies whether this function requires a user activation context to execute." } }, "required": ["returnType"] }, { "if": { "properties": { "requiresUserActivation": {"const": true} }, "required": ["requiresUserActivation"] }, "then": { "properties": { "allowedCallers": {"enum": ["rendererOnly"]} } } } ], "unevaluatedProperties": false }, "LeafDefinition": { "type": "object", "description": "Describes a reusable leaf data type (e.g. design token, value union, or payload structure). Must not define a component schema.", "allOf": [ { "$ref": "https://json-schema.org/draft/2020-12/schema" }, { "not": { "anyOf": [ { "properties": { "properties": { "type": "object", "properties": { "component": { "type": "object", "required": ["const"] } }, "required": ["component"] } }, "required": ["properties"] }, { "properties": { "allOf": { "type": "array", "contains": { "properties": { "properties": { "type": "object", "properties": { "component": { "type": "object", "required": ["const"] } }, "required": ["component"] } }, "required": ["properties"] } } }, "required": ["allOf"] } ] } } ] }, "ComponentDefinition": { "type": "object", "description": "Describes a component's validation schema and composition constraints.", "allOf": [ { "$ref": "https://json-schema.org/draft/2020-12/schema" }, { "type": "object", "properties": { "allowedParents": { "type": "array", "items": { "type": "string" }, "description": "The list of parent component type names that can contain this component type. If omitted, all parent component types are allowed. To restrict a component so it can appear only as the top-level component (id='root') of a surface, set \"allowedParents\": [\"Surface\"]. To allow a component as either the top-level component of a surface or a child of a specific container, specify both (e.g., \"allowedParents\": [\"Surface\", \"CanvasContainer\"]).", "uniqueItems": true }, "allowedChildren": { "type": "array", "items": { "type": "string" }, "description": "The list of child component type names allowed inside this container or slot. If omitted, all child component types are allowed.", "uniqueItems": true }, "metadata": { "type": "object", "description": "Optional static metadata.", "properties": { "extensions": { "$ref": "common_types.json#/$defs/Extensions" } }, "additionalProperties": false } }, "not": { "anyOf": [{"required": ["anyOf"]}, {"required": ["oneOf"]}] } } ] }, "ValidationResult": { "type": "object", "description": "Dynamic validation result object returned by a validation condition function or data binding.", "properties": { "valid": { "type": "boolean", "description": "Whether the check passed." }, "code": { "type": "string", "description": "Machine-readable error code (e.g. EXPIRED_CARD, OUT_OF_RANGE)." }, "message": { "type": "string", "description": "Human-readable error or warning message." }, "severity": { "type": "string", "enum": ["error", "warning", "info"], "default": "error", "description": "Severity level of the validation result." } }, "required": ["valid"] } }}renderer_data_model.json
A2UI Renderer Data Model Schema — Schema for conveying the renderer data models for all active surfaces. This is used for bidirectional data synchronization between the renderer and the agent.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/renderer_data_model.json", "title": "A2UI Renderer Data Model Schema", "description": "Schema for conveying the renderer data models for all active surfaces. This is used for bidirectional data synchronization between the renderer and the agent.", "type": "object", "properties": { "version": { "const": "1.0" }, "surfaces": { "type": "object", "description": "A map of surface IDs to their current data models.", "additionalProperties": { "type": "object", "description": "The current data model for the surface, as a standard JSON object." } } }, "required": ["version", "surfaces"], "additionalProperties": false}Capabilities
agent_capabilities.json
A2UI Agent Capabilities Schema — A schema for the agent capabilities object, which is used by an A2UI Agent to advertise its supported UI features to renderers. This can be embedded in an Agent Card for A2A or used in other transport protocols like MCP.
Definitions & properties (1)
Properties:
1.0{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/agent_capabilities.json", "title": "A2UI Agent Capabilities Schema", "description": "A schema for the agent capabilities object, which is used by an A2UI Agent to advertise its supported UI features to renderers. This can be embedded in an Agent Card for A2A or used in other transport protocols like MCP.", "type": "object", "properties": { "1.0": { "type": "object", "description": "The agent capabilities structure for version 1.0 of the A2UI protocol.", "properties": { "supportedCatalogIds": { "type": "array", "description": "An array of strings, where each is an ID identifying a Catalog for which the agent can generate content. This is not a resolvable URI. Multiple catalogs can be mixed in a single surface.", "items": {"type": "string"} }, "acceptsInlineCatalogs": { "type": "boolean", "description": "A boolean indicating if the agent can accept an 'inlineCatalogs' array in the renderer's a2uiRendererCapabilities. If omitted, this defaults to false.", "default": false } } } }, "required": ["1.0"]}renderer_capabilities.json
A2UI Renderer Capabilities Schema — A schema for the a2uiRendererCapabilities object, which is sent from the renderer to the agent as part of the A2A metadata to describe the renderer's UI rendering capabilities.
Definitions & properties (1)
Properties:
1.0{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/renderer_capabilities.json", "title": "A2UI Renderer Capabilities Schema", "description": "A schema for the a2uiRendererCapabilities object, which is sent from the renderer to the agent as part of the A2A metadata to describe the renderer's UI rendering capabilities.", "type": "object", "properties": { "1.0": { "type": "object", "description": "The capabilities structure for version 1.0 of the A2UI protocol.", "properties": { "supportedCatalogIds": { "type": "array", "description": "An array of string identifiers for each of the component and function catalogs supported by the renderer. Multiple catalogs can be mixed in a single surface.", "items": {"type": "string"} }, "inlineCatalogs": { "type": "array", "description": "An array of inline catalog definitions, which can contain both components and functions. This should only be provided if the agent declares 'acceptsInlineCatalogs: true' in its capabilities.", "items": { "$ref": "https://a2ui.org/specification/v1_0/catalog_definition.json" } } }, "required": ["supportedCatalogIds"] } }, "required": ["1.0"]}Batching and wrappers
agent_to_renderer_list.json
A2UI Agent-to-Renderer Message List — A list of A2UI Agent-to-Renderer messages.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/json/agent_to_renderer_list.json", "title": "A2UI Agent-to-Renderer Message List", "description": "A list of A2UI Agent-to-Renderer messages.", "type": "array", "items": { "$ref": "https://a2ui.org/specification/v1_0/agent_to_renderer.json" }}renderer_to_agent_list.json
A2UI Renderer-to-Agent Message List — A list of A2UI Renderer-to-Agent messages.
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/json/renderer_to_agent_list.json", "title": "A2UI Renderer-to-Agent Message List", "description": "A list of A2UI Renderer-to-Agent messages.", "type": "array", "items": { "$ref": "https://a2ui.org/specification/v1_0/renderer_to_agent.json" }}agent_to_renderer_list_wrapper.json
A2UI Agent-to-Renderer Message List Wrapper — An object wrapping a list of A2UI Agent-to-Renderer messages. Intended for protocols that require a top-level JSON object instead of a raw array.
Definitions & properties (1)
Properties:
messages{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/json/agent_to_renderer_list_wrapper.json", "title": "A2UI Agent-to-Renderer Message List Wrapper", "description": "An object wrapping a list of A2UI Agent-to-Renderer messages. Intended for protocols that require a top-level JSON object instead of a raw array.", "type": "object", "properties": { "messages": { "$ref": "agent_to_renderer_list.json" } }, "additionalProperties": false, "required": ["messages"]}renderer_to_agent_list_wrapper.json
A2UI Renderer-to-Agent Message List Wrapper — An object wrapping a list of A2UI Renderer-to-Agent messages. Intended for protocols that require a top-level JSON object instead of a raw array.
Definitions & properties (1)
Properties:
messages{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://a2ui.org/specification/v1_0/json/renderer_to_agent_list_wrapper.json", "title": "A2UI Renderer-to-Agent Message List Wrapper", "description": "An object wrapping a list of A2UI Renderer-to-Agent messages. Intended for protocols that require a top-level JSON object instead of a raw array.", "type": "object", "properties": { "messages": { "$ref": "renderer_to_agent_list.json" } }, "additionalProperties": false, "required": ["messages"]}