Schema — AFS 1.1 #
Wire-compatible with the Agentation Format Schema,
with one deliberate difference: comment (and every thread message) is Markdown,
not plaintext — so a single annotation can carry inline images, code, and links.
| Field | Type | Notes | |
|---|---|---|---|
id | req | string | ULID; generated if omitted. |
comment | req | string | Markdown. The annotation body. |
elementPath | req | string | Short, human-readable selector (id / data-testid / tag.class). |
element | req | string | Tag name of the target. |
x / y | req | number | x = % of viewport width; y = px from doc top (or viewport if fixed). |
timestamp | req | number | Epoch ms. |
url | opt | string | Page URL at capture. |
boundingBox | opt | BoundingBox | { x, y, width, height }, document-relative. |
fullPath | opt | string | Canonical CSS path from <body> (re-query key). |
selectedText | opt | string | Set for text-selection annotations. |
isMultiSelect | opt | boolean | True for multi-element; see elementBoundingBoxes. |
elementBoundingBoxes | opt | BoundingBox[] | Per-element rects of the selected set. |
reactComponents | opt | string | Nearest named React component(s) + props. |
computedStyles | opt | string | Curated layout-relevant computed CSS. |
cssClasses / accessibility / nearbyText / nearbyElements | opt | string | Forensic disambiguators. |
intent | opt | enum | fix · change · question · approve |
severity | opt | enum | blocking · important · suggestion |
kind | opt | enum | feedback (default) · placement · rearrange |
status | opt | enum | pending · acknowledged · resolved · dismissed |
thread | opt | ThreadMessage[] | { id, role, content (Markdown), timestamp } |
author | opt | object | { kind: "human" | "agent", id?, displayName? } |