Surfaces (kletso.ui/v1)

The surface document, component nodes, bindings, limits and validation, and the props of all 30 built-in component types.

Document

{
  "schema": "kletso.ui/v1",
  "surfaceId": "sfc_01J8HOTEL00001",
  "root": "card1",
  "components": { "card1": { "type": "card", "props": { "title": "Shibuya Grand Hotel", "children": ["price", "b1"] } },
                  "price": { "type": "text", "props": { "text": { "path": "/hotel/priceLabel" }, "style": "title" } },
                  "b1": { "type": "button", "props": { "label": "Book" },
                          "actions": [ { "id": "book", "kind": "agent", "value": { "intent": "book", "hotelId": "h_1" }, "label": "Book Shibuya Grand" } ] } },
  "data": { "hotel": { "priceLabel": "$120 / night" } },
  "fallbackText": "Shibuya Grand Hotel, $120 per night. Book?"
}

Component node

"b1": { "type": "button", "props": { "label": "Book" }, "actions": [ { "id": "book", "kind": "agent", "value": {} } ] }

• type: a built-in name or a namespaced custom type (acme.productCard).
• props: object; container types reference children by id in props.children (and items[].children for tabs and accordion, fields for forms).
• actions: up to 200; a button must have at least one. See Actions for the six kinds.

Bindings

A prop value of the form { "path": "/hotel/priceLabel" } is a JSON pointer (RFC 6901) resolved against data. Paths under /host/ resolve against the app’s host data first. Missing targets drop the prop so the widget uses its default. Only top-level props are resolved. Props typed “string or binding” accept either.

Limits and validation

Other fatal issues: invalidSchema, missingRoot, cycle, missingFallback. Non-fatal (rendered with degradation): danglingChild, buttonWithoutAction, unresolvedBinding, unknownComponent, unreachableComponent. The runtime rejects fatal surfaces before they reach the app and tells the model what to fix; the SDK re-validates and never throws.

A ui.patch event can later change a surface: data is deep-merged, components entries replace by id, null removes.

Built-in types

URLs must be https:// (or r2:// for Kletso-hosted media). Custom types are validated against the props schema you synced.

Fixtures

hotel_card, flight_card, product_cards (custom type in a carousel), quick_replies, form, confirm, chart, catalog_all (every type), media_hub (map, countdown, video, audio, rating), trip_plan (progress, tabs, steps, accordion). Invalid fixtures cover every fatal and non-fatal issue code.