action-topology-engine/schemas/topology-graph.schema.md

Topology Graph Schema

This document describes the JSON shape emitted by the engine. It is a practical schema note, not yet a formal JSON Schema file.

TopologyGraph

• schemaVersion: currently 0.1.
• metadata.entryUrl: entry URL after Playwright navigation.
• metadata.mode: scan or explore.
• states: page states.
• elements: actionable elements bound to a state.
• edges: observed actions from one state to another.

StateNode

• stateId: stable id derived from URL, DOM hash, visible text hash, and actionable signature hash.
• url, route, title: browser-visible state identity.
• domHash: hash of full document.documentElement.outerHTML.
• visibleTextHash: hash of normalized visible body text.
• actionableSignatureHash: hash of actionable element signatures.
• modalStack: visible dialogs or modal-like surfaces.
• openedByEdgeId: edge that opened this state, if known.

ActionableElement

• elementId: stable id within the captured state.
• stateId: owning state.
• tag, role, accessibleName, text, label, placeholder: semantic identity.
• attributes: selected stable attributes such as data-testid, id, name, type, href, and ARIA fields.
• bbox: page-space bounding box.
• interactability: visibility, enabled/editable status, and whether the element receives events.
• locators: scored locator candidates.

LocatorCandidate

• descriptor: structured Playwright locator descriptor.
• expression: human-readable locator expression.
• score: ranking score.
• verified: whether it resolved to exactly one element during capture.
• matchCount: observed locator match count.

ActionEdge

• fromStateId, toStateId: source and resulting states.
• elementId: action target.
• actionType: currently focused on click, with type support for future fill, select, and navigation actions.
• preconditions: reserved for stored open paths.
• effects: URL, visible text, network, download, dialog, storage, or DOM effects.
• riskLevel: low, medium, or high.
• confidence: confidence in observed edge replayability.