Schema
Node Structure
The schema for individual UI elements in the CUP tree.
Overview
Each node in the CUP tree represents a UI element. Nodes are recursive — they can contain child nodes.
Structure
{
"id": "e14",
"role": "button",
"name": "Submit",
"description": "Submit the form",
"value": null,
"bounds": { "x": 120, "y": 340, "w": 88, "h": 36 },
"states": ["focused"],
"actions": ["click"],
"attributes": {
"level": null,
"placeholder": null,
"orientation": null
},
"children": [],
"platform": {
"windows": {
"controlType": "Button",
"automationId": "submitBtn"
}
}
}Core fields
| Field | Type | Description |
|---|---|---|
id | string | Element ID, pattern e\d+ (e.g., e0, e14) |
role | string | One of 59 canonical ARIA-derived roles |
name | string | Accessible name (max 200 chars) |
description | string? | Secondary accessible description |
value | string? | Current value for inputs, sliders |
bounds | object | Bounding rectangle { x, y, w, h } |
states | array | Active state flags (16 possible) |
actions | array | Available interaction verbs (15 possible) |
children | array | Nested child nodes |
Attributes
Optional semantic attributes:
| Attribute | Type | Description |
|---|---|---|
level | int? | Heading level (1-6) |
valueMin | number? | Minimum range value |
valueMax | number? | Maximum range value |
valueNow | number? | Current range value |
orientation | string? | horizontal or vertical |
rowIndex | int? | Table row index |
colIndex | int? | Table column index |
rowCount | int? | Total table rows |
colCount | int? | Total table columns |
posInSet | int? | Position in set (1-indexed) |
setSize | int? | Total set size |
placeholder | string? | Input placeholder text |
url | string? | Link or image target URL |
live | string? | ARIA live region: polite, assertive, off |
autocomplete | string? | inline, list, both, none |
keyShortcut | string? | Keyboard shortcut |
roledescription | string? | Custom role description |
Platform-specific properties
The platform field preserves raw native properties for advanced use cases:
| Platform | Key properties |
|---|---|
| Windows | controlType, automationId, className, patterns, hwnd |
| macOS | axRole, axSubrole, axIdentifier, axActions |
| Linux | atspiRole, interfaces |
| Web | tagName, ariaRole, selector, xpath, inputType |
| Android | className, resourceId, packageName |
| iOS | elementType, identifier, traits |