Skip to main content

​
A2UI Schema v1.0

The A2UI protocol defines how the FERAL brain sends structured UI to any client renderer (iOS, web, Android, CLI).

​
Version

All A2UI messages include "a2ui_version": "1.0". Receivers should check compatibility before rendering.

​
Message Types

TypePurpose
beginRenderingInitial surface with full component tree + data model
surfaceUpdateIncremental component patches
dataModelUpdateData-only patches (re-render bound values)
deleteSurfaceRemove a surface from the client

​
Message Envelope

{
  "a2ui_version": "1.0",
  "type": "beginRendering | surfaceUpdate | dataModelUpdate | deleteSurface",
  "surfaceId": "string",
  ...payload fields
}

​
Component Schema

Every component in the tree has:
FieldTypeRequiredDescription
componentIdstringyesUnique ID within the surface
typeComponentTypeyesOne of the registered types below
propertiesobjectnoType-specific props (value, label, color, etc.)
childrenstring[]noOrdered list of child componentIds

​
Core Component Types

TypeCategoryDescription
TextDisplayText with style variants (headline, subtitle, body, caption)
ImageDisplayImage from URL or data URI
IconDisplayNamed icon (Lucide set)
ButtonInputInteractive button with action_id
CheckboxInputBoolean toggle
TextFieldInputText input
SliderInputNumeric range input
RowLayoutHorizontal layout
ColumnLayoutVertical layout
ListLayoutScrollable list
CardLayoutElevated card container
TabsLayoutTabbed sections
DividerLayoutHorizontal rule
ModalLayoutOverlay dialog

​
FERAL Extensions

TypeDescription
MapViewInteractive map with markers
ChartLine/bar/pie chart
MetricCardNumeric metric with icon + unit
GraphViewKnowledge graph (nodes + links)
CodeBlockSyntax-highlighted code
ProgressBar0-1 progress indicator
TableTabular data (headers + rows)
WebViewEmbedded iframe

​
Data Binding

String values support data-model binding: 
{ "literalString": "Hello" }
{ "path": "user/name" }
Paths are resolved against the surface’s dataModel using /-separated keys.

​
Compatibility

  • Clients that receive an unknown a2ui_version should render a fallback “update required” message.
  • Unknown component types should render as invisible placeholders, not crash.