# Anchored Metadata operations

> Attach a JSON payload to a span of text and read it back across DOCX round-trips. Backed by hidden inline content controls and namespaced Custom XML Data Storage Parts; consumers see one operation set.



6 operations. Names, descriptions, and behavior flags come from the canonical contract.

## Operations

- [`metadata.attach`](/document-api/reference/metadata/attach) (mutates): Anchor a JSON metadata payload to a span of text. Wraps the target range in a hidden inline content control whose w:tag carries a stable id, and stores the payload in a namespaced Custom XML Data Storage Part. v1 supports text-range anchors only.
- [`metadata.list`](/document-api/reference/metadata/list) (read): List anchored-metadata entries in the document, optionally filtered by consumer namespace and/or a `within` selection (returns only entries whose anchor overlaps `within`).
- [`metadata.get`](/document-api/reference/metadata/get) (read): Get a single anchored-metadata entry by id, including its JSON payload.
- [`metadata.update`](/document-api/reference/metadata/update) (mutates): Replace the JSON payload of an existing anchored-metadata entry. Replace semantics; no merge. The anchor is left untouched.
- [`metadata.remove`](/document-api/reference/metadata/remove) (mutates): Remove an anchored-metadata entry. Strips the anchor content-control wrapper (its content stays in the document) and deletes the payload entry from the Storage Part. In v1 these writes are sequenced, not transactional: the adapter resolves the target up-front so missing-target failures land before any state change, but a crash strictly between the two writes can leave a dangling payload. When the backing part has no remaining entries, the part itself is removed.
- [`metadata.resolve`](/document-api/reference/metadata/resolve) (read): Find where an anchored-metadata entry is anchored in the document. Returns the SelectionTarget covering the anchor content.