UIAP Capability Model

UIAP Capability Model v0.1

Field	Value
Status	Draft
Version	0.1
Date	2026-03-27
Dependencies	—
Editors	Patrick

1. Purpose

The Capability Model describes what an application can semantically present, observe, and execute.

It cleanly separates:

Roles: what a UI entity is
States: what state it is in
Affordances: which interactions it fundamentally offers
Actions: which standardized requests the agent can send
Risk: how strictly an action must be regulated
Success Signals: how success can be observed

This is the difference between “there is some button” and “this is video.submit, activatable, requires confirmation, success = route changes and a toast appears”.

2. General Model Rules

Capability values SHOULD be stable and machine-readable.
Core values are reserved without prefix.
Vendor-/app-specific extensions SHOULD begin with x., e.g. x.videoland.asset-card.
A capability document MAY support only a subset of the core vocabulary; the actually supported values MUST be explicitly declared.
Roles and affordances describe semantics, not concrete DOM structures or CSS.

3. Base Types

type ProfileId = string;        // e.g. "[email protected]"
type StableId = string;         // stable, app-defined target ID
type ScopeId = string;          // logical scope, e.g. "create-video-dialog"
type ActionId = string;         // e.g. "ui.activate" or "video.create"

3.1 Target Reference

type TargetRef =
  | { by: "stableId"; value: StableId }
  | { by: "scope"; value: ScopeId }
  | { by: "route"; value: string }
  | { by: "semantic"; role: UIRole; name?: string; scope?: ScopeId }
  | { by: "custom"; value: string };

4. UI Roles

UIRole is the canonical typing of visible or interactive UI objects.

type UIRole =
  // App / Structure
  | "app"
  | "route"
  | "region"
  | "group"
  | "form"
  | "dialog"
  | "drawer"
  | "popover"
  | "tabpanel"

  // Navigation / Structured Selection
  | "link"
  | "menu"
  | "menuitem"
  | "tablist"
  | "tab"
  | "toolbar"
  | "breadcrumb"
  | "pagination"

  // Collections
  | "list"
  | "listitem"
  | "table"
  | "row"
  | "cell"
  | "grid"
  | "tree"
  | "treeitem"

  // Inputs / Controls
  | "button"
  | "textbox"
  | "textarea"
  | "searchbox"
  | "combobox"
  | "listbox"
  | "option"
  | "checkbox"
  | "radio"
  | "switch"
  | "slider"
  | "spinbutton"
  | "datepicker"
  | "timepicker"
  | "fileinput"
  | "label"

  // Feedback / Status
  | "alert"
  | "toast"
  | "status"
  | "progress"
  | "spinner"

  // Media / Special Cases
  | "image"
  | "video"
  | "audio"
  | "canvas"

  // Escape hatch
  | "custom";

4.1 Role Semantics

button: activatable command
textbox / textarea: editable text input
checkbox / radio / switch: discrete state selection
combobox / listbox / option: selection from candidates
dialog / drawer / popover: temporary UI surfaces
toast / alert / status: observable feedback signals
custom: only when no core role fits

5. UI States

UIState describes the observable state of an element or scope.

interface UIState {
  visible?: boolean;
  enabled?: boolean;
  focusable?: boolean;
  focused?: boolean;
  editable?: boolean;
  readonly?: boolean;
  required?: boolean;

  busy?: boolean;
  loading?: boolean;
  blocked?: boolean;

  selected?: boolean;
  checked?: boolean | "mixed";
  pressed?: boolean;
  expanded?: boolean;
  open?: boolean;
  modal?: boolean;

  hovered?: boolean;
  dragged?: boolean;

  current?: false | "page" | "step" | "location" | "date" | "time";
  invalid?: false | true | "grammar" | "spelling";

  multiline?: boolean;
  hasPopup?: false | "menu" | "listbox" | "dialog" | "grid" | "tree";
  orientation?: "horizontal" | "vertical";

  textValue?: string;
  numericValue?: number;
  min?: number;
  max?: number;
  step?: number;

  placeholder?: string;
  description?: string;

  sensitive?: boolean;
  obscured?: boolean;
}

5.1 State Keys

A capability document SHOULD additionally declare which state keys are actively emitted.

type UIStateKey = keyof UIState;

5.2 State Rules

visible=false does not automatically imply enabled=false.
blocked=true means: formally present but currently not usable.
sensitive=true marks data or controls that require special policy treatment.
obscured=true marks content that is covered or intentionally masked.

6. Affordances

Affordances describe which type of interaction an element fundamentally offers.

type UIAffordance =
  | "read"
  | "focus"
  | "activate"
  | "edit"
  | "choose"
  | "toggle"
  | "expand"
  | "collapse"
  | "open"
  | "close"
  | "scroll"
  | "submit"
  | "dismiss"
  | "drag"
  | "drop"
  | "resize"
  | "upload"
  | "navigate"
  | "invoke";

6.1 Affordance Semantics

activate: generic activation, e.g. button, link, card
edit: text or value can be modified
choose: selection from options
toggle: binary or tri-state switch
invoke: domain-level app action beyond a simple click

6.2 Important Distinction

Affordance = what an element can principally offer
Action = standardized request from the agent

A button typically has the activate affordance. The agent then sends e.g. ui.activate.

7. Actions

Actions are standardized executable operations.

7.1 Primitive Actions

type PrimitiveActionType =
  | "ui.read"
  | "ui.focus"
  | "ui.highlight"
  | "ui.hover"
  | "ui.activate"
  | "ui.enterText"
  | "ui.clearText"
  | "ui.setValue"
  | "ui.choose"
  | "ui.toggle"
  | "ui.expand"
  | "ui.collapse"
  | "ui.open"
  | "ui.close"
  | "ui.scrollIntoView"
  | "ui.scroll"
  | "ui.submit"
  | "ui.upload"
  | "nav.navigate"
  | "app.invoke";

7.2 Execution Modes

type ExecutionMode =
  | "appAction"        // direct app function / registry
  | "semanticUi"       // semantic UI target addressing
  | "inputSynthesis"   // synthetic pointer/keyboard input
  | "externalDriver"   // external automation driver
  | "visionAssist";    // vision-assisted fallback

7.3 Action Descriptor

interface ActionDescriptor {
  id: ActionId;                        // "ui.activate" or "video.create"
  kind: "primitive" | "domain";
  title?: string;
  description?: string;

  targetKinds: Array<"element" | "scope" | "route" | "entity" | "session" | "none">;
  requiredAffordances?: UIAffordance[];
  executionModes: ExecutionMode[];

  args?: ActionArgDescriptor[];
  idempotency?: "idempotent" | "conditional" | "non_idempotent";

  risk: RiskDescriptor;
  success?: SuccessSignal[];

  metadata?: Record<string, unknown>;
}

interface ActionArgDescriptor {
  name: string;
  type: "string" | "number" | "boolean" | "enum" | "object" | "array";
  required?: boolean;
  enum?: string[];
  description?: string;
}

7.4 Domain Actions

In addition to primitive actions, an application MAY declare domain-specific actions, e.g.:

video.create
workspace.setup
team.invite
billing.openSettings

These SHOULD be stable, dot-segmented, and named with domain semantics.

7.5 Entity Awareness

Capability documents MAY additionally specify which entity types a capability or action relates to.

Example optional fields:

entityTypes?: string[]
targetKinds?: Array<"ui" | "entity">

Rules

entityTypes describe the semantic subject of a capability, not its permission.
targetKinds MAY indicate whether an action works only with UI targets, only with entity targets, or with both.
When targetKinds contains entity, the corresponding runtime specification SHOULD define an entityRef semantic.

8. Risk Model

This is intentionally separated cleanly, because people otherwise tend to squeeze five entirely different risks into a single word.

8.1 Effective Risk Level

RiskLevel controls executability.

type RiskLevel =
  | "safe"      // autonomously executable within granted scopes
  | "confirm"   // explicit user confirmation required
  | "blocked";  // not automatically executable

8.2 Risk Tags

RiskTag describes the domain-level cause or class of the risk.

type RiskTag =
  | "sensitive_data"
  | "destructive"
  | "external_effect"
  | "privileged"
  | "billing"
  | "security"
  | "identity"
  | "legal"
  | "irreversible";

8.3 Risk Descriptor

interface RiskDescriptor {
  level: RiskLevel;
  tags?: RiskTag[];
  reason?: string;
}

8.4 Risk Semantics

safe: e.g. opening a route, switching a tab, writing a text suggestion into a draft
confirm: e.g. creating a record, sending an invitation, saving settings
blocked: e.g. changing a password, triggering a payment, deleting a user, irreversible publish action

8.5 Risk Rules

When multiple risk tags apply, the strictest level wins.
blocked MUST NOT be executed autonomously.
confirm SHOULD require a human confirmation point before execution.

9. Success Signals

Success Signals are observable predicates, not wishes and not prompt-based superstition.

9.1 Signal Classes

type SuccessSignal =
  | { kind: "element.appeared"; target: TargetRef }
  | { kind: "element.disappeared"; target: TargetRef }
  | { kind: "element.state"; target: TargetRef; state: Partial<UIState> }
  | { kind: "value.equals"; target: TargetRef; value: string | number | boolean }
  | { kind: "route.changed"; pattern?: string; exact?: string }
  | { kind: "dialog.opened"; target?: TargetRef }
  | { kind: "dialog.closed"; target?: TargetRef }
  | { kind: "toast.contains"; text: string }
  | { kind: "status.contains"; text: string }
  | { kind: "validation.none"; scope?: ScopeId }
  | { kind: "collection.count"; target: TargetRef; op: "eq" | "gte" | "lte"; value: number }
  | { kind: "entity.created"; entityType: string; idPath?: string }
  | { kind: "entity.updated"; entityType: string; idPath?: string }
  | { kind: "entity.deleted"; entityType: string; idPath?: string }
  | { kind: "network.response"; urlPattern?: string; status?: number }
  | { kind: "custom"; name: string; payload?: Record<string, unknown> };

9.2 Signal Rules

Signals SHOULD be declarative and observable.
An action descriptor SHOULD contain at least one expected success signal.
custom SHOULD only be used when no core signal fits.
For critical domain actions, multiple success signals SHOULD be combined.

Example: video.create

route.changed to /videos/:id
toast.contains = "erstellt"
optionally entity.created = "video"

10. Capability Document

The capability document is the comprehensive description of active capabilities.

interface CapabilityDocument {
  modelVersion: "0.1";
  profile: ProfileId;                    // e.g. "[email protected]"

  roles: UIRole[];
  stateKeys: UIStateKey[];
  affordances: UIAffordance[];

  actions: ActionDescriptor[];

  riskLevels: RiskLevel[];
  riskTags?: RiskTag[];

  successSignalKinds: string[];

  metadata?: Record<string, unknown>;
}

10.1 Rules

roles, stateKeys, affordances, actions, riskLevels MUST be present.
An app MUST only declare values that are actually supported.
successSignalKinds SHOULD contain all kind values used in the document.

11. Example Capability Document

{
  "modelVersion": "0.1",
  "profile": "[email protected]",
  "roles": [
    "route",
    "dialog",
    "form",
    "button",
    "textbox",
    "textarea",
    "toast",
    "status"
  ],
  "stateKeys": [
    "visible",
    "enabled",
    "focused",
    "required",
    "open",
    "invalid",
    "textValue",
    "sensitive"
  ],
  "affordances": [
    "read",
    "focus",
    "activate",
    "edit",
    "submit",
    "navigate",
    "invoke"
  ],
  "actions": [
    {
      "id": "ui.activate",
      "kind": "primitive",
      "targetKinds": ["element"],
      "requiredAffordances": ["activate"],
      "executionModes": ["appAction", "semanticUi", "inputSynthesis"],
      "risk": { "level": "safe" }
    },
    {
      "id": "ui.enterText",
      "kind": "primitive",
      "targetKinds": ["element"],
      "requiredAffordances": ["edit"],
      "executionModes": ["appAction", "semanticUi", "inputSynthesis"],
      "args": [
        { "name": "text", "type": "string", "required": true }
      ],
      "risk": { "level": "safe" }
    },
    {
      "id": "video.create",
      "kind": "domain",
      "title": "Video erstellen",
      "targetKinds": ["scope"],
      "executionModes": ["appAction", "semanticUi"],
      "args": [
        { "name": "title", "type": "string", "required": true },
        { "name": "useCase", "type": "string", "required": false }
      ],
      "idempotency": "non_idempotent",
      "risk": {
        "level": "confirm",
        "tags": ["external_effect"]
      },
      "success": [
        { "kind": "route.changed", "pattern": "/videos/:id" },
        { "kind": "toast.contains", "text": "erstellt" }
      ]
    }
  ],
  "riskLevels": ["safe", "confirm", "blocked"],
  "riskTags": [
    "sensitive_data",
    "destructive",
    "external_effect",
    "privileged"
  ],
  "successSignalKinds": [
    "route.changed",
    "toast.contains",
    "element.state",
    "validation.none"
  ]
}

Normative References

[UIAP-CORE] UIAP Core v0.1
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels, BCP 14

Security Considerations

Capability documents MAY contain security-relevant information (e.g. available admin actions). Access to capability information SHOULD be restricted to authorized agents.
Risk levels MUST be declared correctly; incorrect classification can lead to unintended actions.
Sensitive fields SHOULD be marked as such in the capability document.

Changelog

Version	Date	Changes
0.1	2026-03-27	Initial draft