# extract

> Extract all document content with stable IDs for RAG pipelines. Returns blocks with full text, comments, and tracked changes: each with an ID compatible with scrollToElement().



- Member path: `doc.extract(…)`
- Mutates document: no
- Idempotency: `idempotent`
- Supports tracked mode: no
- Supports dry run: no

## Expected result

Returns an ExtractResult with blocks (nodeId, type, text, headingLevel), comments (entityId, text, anchoredText, blockId, status, author), tracked changes (entityId, type, excerpt, author, date), and revision.

## Input schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

## Output schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$defs": {},
  "type": "object",
  "properties": {
    "blocks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nodeId": {
            "type": "string",
            "description": "Stable block ID: pass to scrollToElement() for navigation."
          },
          "type": {
            "type": "string",
            "description": "Block type: paragraph, heading, listItem, image, tableOfContents."
          },
          "text": {
            "type": "string",
            "description": "Full plain text content of the block."
          },
          "textSpans": {
            "type": "array",
            "description": "Block text broken into runs with tracked-change marks preserved per run. Present only when the block contains at least one tracked change. Concatenating span text yields `text`.",
            "items": {
              "type": "object",
              "properties": {
                "text": {
                  "type": "string",
                  "description": "Raw text of the run."
                },
                "trackedChanges": {
                  "type": "array",
                  "description": "Tracked-change marks applied to this run.",
                  "items": {
                    "type": "object",
                    "properties": {
                      "entityId": {
                        "type": "string",
                        "description": "Tracked change entity ID matching an entry in trackedChanges[]."
                      },
                      "type": {
                        "type": "string",
                        "enum": [
                          "insert",
                          "delete",
                          "format"
                        ]
                      }
                    },
                    "additionalProperties": false,
                    "required": [
                      "entityId",
                      "type"
                    ]
                  }
                }
              },
              "additionalProperties": false,
              "required": [
                "text"
              ]
            }
          },
          "headingLevel": {
            "type": "integer",
            "description": "Heading level (1-6). Only present for headings."
          },
          "tableContext": {
            "type": "object",
            "properties": {
              "tableOrdinal": {
                "type": "integer",
                "description": "0-based table ordinal, unique within one extract() result."
              },
              "parentTableOrdinal": {
                "type": "integer",
                "description": "Ordinal of the parent table when the containing table is nested."
              },
              "parentRowIndex": {
                "type": "integer",
                "description": "Row index in the parent table. Set with parentTableOrdinal."
              },
              "parentColumnIndex": {
                "type": "integer",
                "description": "Column index in the parent table. Set with parentTableOrdinal."
              },
              "rowIndex": {
                "type": "integer",
                "description": "0-based row index of the containing cell."
              },
              "columnIndex": {
                "type": "integer",
                "description": "0-based logical grid column, not the row child order."
              },
              "rowspan": {
                "type": "integer",
                "description": "Number of rows the cell spans."
              },
              "colspan": {
                "type": "integer",
                "description": "Number of columns the cell spans."
              }
            },
            "additionalProperties": false,
            "required": [
              "tableOrdinal",
              "rowIndex",
              "columnIndex",
              "rowspan",
              "colspan"
            ]
          }
        },
        "additionalProperties": false,
        "required": [
          "nodeId",
          "type",
          "text"
        ]
      }
    },
    "comments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entityId": {
            "type": "string",
            "description": "Comment entity ID: pass to scrollToElement() for navigation."
          },
          "text": {
            "type": "string",
            "description": "Comment body text."
          },
          "anchoredText": {
            "type": "string",
            "description": "The document text the comment is anchored to."
          },
          "blockId": {
            "type": "string",
            "description": "Block ID the comment is anchored to."
          },
          "status": {
            "type": "string",
            "enum": [
              "open",
              "resolved"
            ]
          },
          "author": {
            "type": "string",
            "description": "Comment author name."
          }
        },
        "additionalProperties": false,
        "required": [
          "entityId",
          "status"
        ]
      }
    },
    "trackedChanges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entityId": {
            "type": "string",
            "description": "Tracked change entity ID. Pass to scrollToElement() for navigation."
          },
          "type": {
            "type": "string",
            "enum": [
              "insert",
              "delete",
              "replacement",
              "format"
            ],
            "description": "Aggregate type at the entity level. In paired replacement mode, a delete+insert pair shares one entity and this surfaces as 'replacement'; per-half type lives on block.textSpans[].trackedChanges[]."
          },
          "blockIds": {
            "type": "array",
            "description": "Block IDs whose textSpans carry this change.",
            "items": {
              "type": "string"
            }
          },
          "wordRevisionIds": {
            "type": "object",
            "properties": {
              "insert": {
                "type": "string",
                "description": "Original OOXML w:id from a w:ins mark."
              },
              "delete": {
                "type": "string",
                "description": "Original OOXML w:id from a w:del mark."
              },
              "format": {
                "type": "string",
                "description": "Original OOXML w:id from a w:rPrChange mark."
              }
            },
            "additionalProperties": false
          },
          "excerpt": {
            "type": "string",
            "description": "Short text excerpt of the changed content. Omitted for paired replacements; read block.textSpans for the per-half text."
          },
          "author": {
            "type": "string",
            "description": "Change author name."
          },
          "date": {
            "type": "string",
            "description": "Change date (ISO string)."
          }
        },
        "additionalProperties": false,
        "required": [
          "entityId",
          "type"
        ]
      }
    },
    "revision": {
      "type": "string",
      "description": "Document revision at the time of extraction."
    }
  },
  "additionalProperties": false,
  "required": [
    "blocks",
    "comments",
    "trackedChanges",
    "revision"
  ]
}
```

## Pre-apply throws

- None

## Non-applied receipt codes

- None