122 lines
7.1 KiB
Markdown
122 lines
7.1 KiB
Markdown
# Topology Graph Schema
|
|
|
|
This document describes the JSON shape emitted by the engine. A formal JSON Schema is also provided in `schemas/topology-graph.schema.json`.
|
|
|
|
## `TopologyGraph`
|
|
|
|
- `schemaVersion`: currently `0.2`.
|
|
- `metadata.artifactVersion`: currently `topology-graph-v0.2`.
|
|
- `metadata.inputUrl`: raw URL or file path supplied by the caller.
|
|
- `metadata.entryUrl`: entry URL after Playwright navigation.
|
|
- `metadata.generatedAt`: ISO timestamp for this artifact generation.
|
|
- `metadata.engineVersion`: engine implementation version that emitted the artifact.
|
|
- `metadata.mode`: `scan` or `explore`.
|
|
- `metadata.crawlSessionId`: unique non-deterministic identifier for this graph generation session. It is intentionally different across runs.
|
|
- `metadata.inputSeed`: caller-supplied input seed. In v0.2 this is the raw `inputUrl`.
|
|
- `metadata.inputFingerprint`: deterministic hash of input URL, mode, and policy/scoring versions.
|
|
- `metadata.runtimeContext`: browser engine, viewport, locale, timezone, and auth context.
|
|
- `metadata.site`: base URL and entry URL.
|
|
- `metadata.riskPolicyVersion`: currently `risk-policy-v0.2`.
|
|
- `metadata.normalizationRuleVersion`: currently `normalization-v0.2`.
|
|
- `metadata.locatorScoringVersion`: currently `locator-scoring-v0.2`.
|
|
- `states`: page states.
|
|
- `elements`: actionable elements bound to a state.
|
|
- `edges`: observed actions from one state to another.
|
|
- `skippedActions`: state-local default-explorer actions that risk policy refused to execute.
|
|
- `failedObservations`: failed locator, actionability, action, or effect observations recorded as evidence.
|
|
- `summary`: machine-readable artifact counts and grouped counts.
|
|
|
|
## Evidence Levels
|
|
|
|
- `observed`: directly captured browser fact.
|
|
- `derived`: deterministic rule output from observed facts.
|
|
- `verified`: re-resolved or replay-verified claim.
|
|
- `heuristic`: conservative inference such as risk classification.
|
|
- `external`: human or downstream annotation.
|
|
|
|
## `StateNode`
|
|
|
|
- `stateId`: stable id derived from URL, normalized state hashes, and actionable signatures.
|
|
- `lifecycle`: `observed`, `fingerprinted`, `verified`, `stale`, `deprecated`, or `conflicted`.
|
|
- `url`, `route`, `urlCanonicalKey`, `title`, `language`, `viewport`: browser-visible and normalized state identity.
|
|
- `stateHash`, `domHash`, `visibleTextHash`, `actionableSignatureHash`: deterministic state fingerprints.
|
|
- `modalStack`: visible modal context.
|
|
- `frameContext`: reserved frame context path. In v0.2.1 this is emitted as an empty array.
|
|
- `openedByEdgeId`: first edge that observed this state in the current run. It is not the only possible predecessor.
|
|
- `createdAt`: ISO timestamp for state capture.
|
|
- `evidence`: observed and derived state facts.
|
|
|
|
## `ActionableElement`
|
|
|
|
- `elementId`: state-local element id. It encodes state identity and must not be treated as a global DOM node id.
|
|
- `stateId`: owning state.
|
|
- `tag`, `role`, `accessibleName`, `text`, `label`, `placeholder`: semantic identity.
|
|
- `attributes`: selected stable attributes such as test id, id, name, type, href, and ARIA fields.
|
|
- `bbox`: geometry.
|
|
- `framePath`, `shadowPath`: reserved containment paths. In v0.2.1 these are emitted as empty arrays.
|
|
- `interactability`: visibility, enabled/editable status, and whether the element receives events.
|
|
- `context`: nearest dialog, form, section, row, landmark, and list item anchors.
|
|
- `parameterSurface`: input/select/textarea constraints, options, required state, pattern, min/max, and maxLength.
|
|
- `locators`: scored locator candidates.
|
|
- `evidence`: observed and derived element facts.
|
|
|
|
## `LocatorCandidate`
|
|
|
|
- `locatorId`: locator candidate id.
|
|
- `elementId`: parent element id. This must equal the containing `ActionableElement.elementId`.
|
|
- `framework`: `playwright` or `css`.
|
|
- `strategy`: locator strategy such as role, label, placeholder, text, test id, CSS, or scoped.
|
|
- `descriptor`: structured locator descriptor.
|
|
- `expression`: human-readable locator expression.
|
|
- `score`, `reason`, `verified`, `matchCount`, `failureCount`, `lastVerifiedAt`: ranking and verification metadata.
|
|
- `scopes`: context-scope evidence such as row, dialog, form, or section anchors.
|
|
- `descriptor.kind: "scoped"`: executable scoped locator descriptor. In v0.2.2 this contains a scope descriptor plus a base target descriptor, with row, dialog, form, and list-item scopes used for execution when available.
|
|
- `identity`: semantic identity checks for tag, role, accessible name, text, and visibility.
|
|
- `evidence`: generation and verification facts.
|
|
|
|
## `ActionEdge`
|
|
|
|
- `edgeId`: action edge id.
|
|
- `fromStateId`, `toStateId`, `elementId`, `actionType`: source state, resulting state if observed, target element, and action kind.
|
|
- `actionParams`, `preconditions`, `parameterSpecs`: action payload and future replay metadata.
|
|
- `effects`: snapshot-diff effects observed after replay.
|
|
- `riskLevel`, `riskCategory`: risk classification used by default exploration.
|
|
- `confidence`: confidence in observed edge replayability.
|
|
- `createdAt`: ISO timestamp for edge capture.
|
|
- In v0.2.1 default exploration replays each edge from a clean entry-state context.
|
|
- Navigation timeout during entry or replay can be recorded as `FailedObservation` instead of aborting artifact generation.
|
|
|
|
## `EffectRecord`
|
|
|
|
- `type`: exactly one of `url`, `dom`, `visibleText`, or `actionableInventory`.
|
|
- `before`, `after`: populated for v0.2.1 snapshot-diff effects.
|
|
- `description`: human-readable effect summary.
|
|
- v0.2.1 emits snapshot-diff effects only: URL, DOM hash, visible text hash, and actionable inventory hash.
|
|
- Network, storage, download, and dialog event buffers are not emitted in v0.2.1 and are future work, not current contract.
|
|
|
|
## `SkippedAction`
|
|
|
|
- `skippedActionId`, `stateId`, `elementId`, `actionType`: state-local skipped action identity.
|
|
- `riskLevel`, `riskCategory`: risk-policy classification.
|
|
- `reason`: policy decision string such as `blocked:destructive`.
|
|
- `evidence`: risk-policy evidence explaining why the action was skipped.
|
|
- `createdAt`: ISO timestamp for the skip record.
|
|
- `SkippedAction` is only for risk-policy default-explorer refusals. Hidden, disabled, obscured, duplicate-locator, locator-not-found, action, and effect failures are `FailedObservation`.
|
|
|
|
## `FailedObservation`
|
|
|
|
- `failedObservationId`, `stateId`, optional `elementId`, optional `actionType`: failed observation identity.
|
|
- `stateId` may be `null` for graph-level failures such as entry navigation timeout before any state exists.
|
|
- `reason`: machine-readable failure code.
|
|
- `message`: diagnostic message.
|
|
- `evidence`: observed facts explaining the failure.
|
|
- `createdAt`: ISO timestamp for the failure record.
|
|
- `FailedObservation` covers hidden, disabled, obscured, locator, action, and effect failures. Risk-policy default-explorer refusals belong in `SkippedAction`.
|
|
|
|
## `summary`
|
|
|
|
- `states`, `elements`, `edges`, `skippedActions`, `failedObservations`: total counts for the artifact.
|
|
- `failedObservationsByReason`: count map keyed by `FailedObservation.reason`.
|
|
- `skippedActionsByRiskCategory`: count map keyed by skipped action risk category.
|
|
- `edgesByRiskCategory`: count map keyed by executed edge risk category.
|