metadata.attach

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.

Summary

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.

• Operation ID: metadata.attach
• API member path: editor.doc.metadata.attach(...)
• Mutates document: yes
• Idempotency: non-idempotent
• Supports tracked mode: no
• Supports dry run: yes
• Deterministic target resolution: yes

Expected result

Returns an AnchoredMetadataAttachResult with the assigned id and the backing Storage Part name on success.

Input fields

Field	Type	Required	Description
id	string	no
namespace	string	yes
payload	any	yes
target	SelectionTarget	yes	SelectionTarget
target.end	SelectionPoint	yes	SelectionPoint
target.kind	"selection"	yes	Constant: "selection"
target.start	SelectionPoint	yes	SelectionPoint

Example request

{
  "id": "id-001",
  "namespace": "urn:customer:metadata:1",
  "payload": {},
  "target": {
    "end": {
      "blockId": "block-abc123",
      "kind": "text",
      "offset": 0
    },
    "kind": "selection",
    "start": {
      "blockId": "block-abc123",
      "kind": "text",
      "offset": 0
    }
  }
}

Output fields

Variant 1 (success=true)

Field	Type	Required	Description
id	string	yes
namespace	string	yes
partName	string	yes
success	true	yes	Constant: true

Variant 2 (success=false)

Field	Type	Required	Description
failure	object	yes
failure.code	string	yes
failure.details	any	no
failure.message	string	yes
success	false	yes	Constant: false

Example response

{
  "id": "id-001",
  "namespace": "urn:customer:metadata:1",
  "partName": "example",
  "success": true
}

Pre-apply throws

• TARGET_NOT_FOUND
• INVALID_TARGET
• INVALID_INPUT
• CAPABILITY_UNAVAILABLE
• REVISION_MISMATCH

Non-applied failure codes

• TARGET_NOT_FOUND
• INVALID_TARGET
• INVALID_INPUT

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "minLength": 1,
      "type": "string"
    },
    "namespace": {
      "minLength": 1,
      "type": "string"
    },
    "payload": {},
    "target": {
      "$ref": "#/$defs/SelectionTarget"
    }
  },
  "required": [
    "target",
    "namespace",
    "payload"
  ],
  "type": "object"
}

Raw output schema

{
  "oneOf": [
    {
      "additionalProperties": false,
      "properties": {
        "id": {
          "minLength": 1,
          "type": "string"
        },
        "namespace": {
          "minLength": 1,
          "type": "string"
        },
        "partName": {
          "minLength": 1,
          "type": "string"
        },
        "success": {
          "const": true
        }
      },
      "required": [
        "success",
        "id",
        "namespace",
        "partName"
      ],
      "type": "object"
    },
    {
      "additionalProperties": false,
      "properties": {
        "failure": {
          "additionalProperties": false,
          "properties": {
            "code": {
              "type": "string"
            },
            "details": {},
            "message": {
              "type": "string"
            }
          },
          "required": [
            "code",
            "message"
          ],
          "type": "object"
        },
        "success": {
          "const": false
        }
      },
      "required": [
        "success",
        "failure"
      ],
      "type": "object"
    }
  ]
}

Raw success schema

{
  "additionalProperties": false,
  "properties": {
    "id": {
      "minLength": 1,
      "type": "string"
    },
    "namespace": {
      "minLength": 1,
      "type": "string"
    },
    "partName": {
      "minLength": 1,
      "type": "string"
    },
    "success": {
      "const": true
    }
  },
  "required": [
    "success",
    "id",
    "namespace",
    "partName"
  ],
  "type": "object"
}

Raw failure schema

{
  "additionalProperties": false,
  "properties": {
    "failure": {
      "additionalProperties": false,
      "properties": {
        "code": {
          "type": "string"
        },
        "details": {},
        "message": {
          "type": "string"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "success": {
      "const": false
    }
  },
  "required": [
    "success",
    "failure"
  ],
  "type": "object"
}