# mutations.preview > Dry-run a mutation plan, returning resolved targets without applying changes. - Member path: `doc.mutations.preview(…)` - Mutates document: no - Idempotency: `idempotent` - Supports tracked mode: no - Supports dry run: no ## Expected result Returns a MutationsPreviewOutput with resolved targets and step details without applying changes. ## Input schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": { "StoryLocator": { "description": "Story scope. Defaults to document body when omitted. Use {kind:'story', storyType:'body'} for body, or other storyType values for headers, footers, footnotes, endnotes.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "body" } }, "additionalProperties": false, "required": [ "kind", "storyType" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterSlot" }, "section": { "$ref": "#/$defs/SectionAddress" }, "headerFooterKind": { "enum": [ "header", "footer" ] }, "variant": { "enum": [ "default", "first", "even" ] }, "resolution": { "enum": [ "effective", "explicit" ] }, "onWrite": { "enum": [ "materializeIfInherited", "editResolvedPart", "error" ] } }, "additionalProperties": false, "required": [ "kind", "storyType", "section", "headerFooterKind", "variant" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "headerFooterPart" }, "refId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "refId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "footnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "endnote" }, "noteId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "noteId" ] }, { "type": "object", "properties": { "kind": { "const": "story" }, "storyType": { "const": "textbox" }, "textboxId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "storyType", "textboxId" ] } ] }, "SectionAddress": { "type": "object", "properties": { "kind": { "const": "section" }, "sectionId": { "type": "string" } }, "additionalProperties": false, "required": [ "kind", "sectionId" ] }, "BlockNodeAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "SelectionTarget": { "type": "object", "properties": { "kind": { "const": "selection" }, "start": { "$ref": "#/$defs/SelectionPoint" }, "end": { "$ref": "#/$defs/SelectionPoint" }, "story": { "$ref": "#/$defs/StoryLocator" }, "coordinateSpace": { "$ref": "#/$defs/TextCoordinateSpace" } }, "additionalProperties": false, "required": [ "kind", "start", "end" ] }, "SelectionPoint": { "description": "A point in the document. Use {kind:'text', blockId, offset} for character positions or {kind:'nodeEdge', node:{kind:'block', nodeType, nodeId}, edge:'before'|'after'} for block boundaries.", "oneOf": [ { "type": "object", "properties": { "kind": { "const": "text" }, "blockId": { "type": "string" }, "offset": { "type": "integer", "minimum": 0 }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "blockId", "offset" ] }, { "type": "object", "properties": { "kind": { "const": "nodeEdge" }, "node": { "$ref": "#/$defs/SelectionEdgeNodeAddress" }, "edge": { "enum": [ "before", "after" ] } }, "additionalProperties": false, "required": [ "kind", "node", "edge" ] } ] }, "SelectionEdgeNodeAddress": { "type": "object", "properties": { "kind": { "const": "block" }, "nodeType": { "enum": [ "paragraph", "heading", "table", "tableOfContents", "sdt", "image" ] }, "nodeId": { "type": "string" }, "story": { "$ref": "#/$defs/StoryLocator" } }, "additionalProperties": false, "required": [ "kind", "nodeType", "nodeId" ] }, "TextCoordinateSpace": { "enum": [ "visible", "tracked" ] }, "DeleteBehavior": { "enum": [ "selection", "exact" ] } }, "type": "object", "properties": { "in": { "$ref": "#/$defs/StoryLocator" }, "expectedRevision": { "type": "string", "description": "Document revision for optimistic concurrency. Mutation fails if document was modified since this revision." }, "atomic": { "const": true, "type": "boolean", "description": "Must be true. All steps execute as one atomic transaction." }, "changeMode": { "enum": [ "direct", "tracked" ], "description": "Required. Use 'direct' for immediate edits or 'tracked' for suggestions. Must always be provided." }, "steps": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "text.rewrite", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search." }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search." }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "replacement": { "oneOf": [ { "type": "object", "properties": { "text": { "type": "string" } }, "additionalProperties": false, "required": [ "text" ] }, { "type": "object", "properties": { "blocks": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" } }, "additionalProperties": false, "required": [ "text" ] } } }, "additionalProperties": false, "required": [ "blocks" ] } ] }, "style": { "type": "object", "properties": { "inline": { "type": "object", "properties": { "mode": { "enum": [ "preserve", "set", "clear", "merge" ], "type": "string" }, "requireUniform": { "type": "boolean" }, "onNonUniform": { "enum": [ "error", "useLeadingRun", "majority", "union" ] }, "setMarks": { "type": "object", "properties": { "bold": { "enum": [ "on", "off", "clear" ] }, "italic": { "enum": [ "on", "off", "clear" ] }, "underline": { "enum": [ "on", "off", "clear" ] }, "strike": { "enum": [ "on", "off", "clear" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "mode" ] }, "paragraph": { "type": "object", "properties": { "mode": { "enum": [ "preserve", "set", "clear" ], "type": "string" } }, "additionalProperties": false, "required": [ "mode" ] } }, "additionalProperties": false, "required": [ "inline" ] } }, "additionalProperties": false, "required": [ "replacement" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "text.insert", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search." }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search." }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "position": { "enum": [ "before", "after" ] }, "content": { "type": "object", "properties": { "text": { "type": "string" } }, "additionalProperties": false, "required": [ "text" ] }, "style": { "type": "object", "properties": { "inline": { "type": "object", "properties": { "mode": { "enum": [ "inherit", "set", "clear" ], "type": "string" }, "setMarks": { "type": "object", "properties": { "bold": { "enum": [ "on", "off", "clear" ] }, "italic": { "enum": [ "on", "off", "clear" ] }, "underline": { "enum": [ "on", "off", "clear" ] }, "strike": { "enum": [ "on", "off", "clear" ] } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "mode" ] } }, "additionalProperties": false, "required": [ "inline" ] } }, "additionalProperties": false, "required": [ "position", "content" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "text.delete", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search." }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search." }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "behavior": { "$ref": "#/$defs/DeleteBehavior" } }, "additionalProperties": false } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "format.apply", "type": "string" }, "where": { "oneOf": [ { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search." }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search." }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" }, "require": { "enum": [ "first", "exactlyOne", "all" ] } }, "additionalProperties": false, "required": [ "by", "select", "require" ] }, { "type": "object", "properties": { "by": { "const": "ref", "type": "string" }, "ref": { "type": "string" }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "ref" ] }, { "type": "object", "properties": { "by": { "const": "target", "type": "string" }, "target": { "$ref": "#/$defs/SelectionTarget" } }, "additionalProperties": false, "required": [ "by", "target" ] }, { "type": "object", "properties": { "by": { "const": "block", "type": "string" }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt" ] }, "nodeId": { "type": "string" } }, "additionalProperties": false, "required": [ "by", "nodeType", "nodeId" ] } ] }, "args": { "type": "object", "properties": { "inline": { "type": "object", "properties": { "bold": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "italic": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "strike": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "underline": { "oneOf": [ { "type": "boolean" }, { "type": "null" }, { "type": "object", "properties": { "style": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "themeColor": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 } ] }, "highlight": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fontSize": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "fontFamily": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "letterSpacing": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vertAlign": { "oneOf": [ { "enum": [ "superscript", "subscript", "baseline" ] }, { "type": "null" } ] }, "position": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "dstrike": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "smallCaps": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "caps": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "shading": { "oneOf": [ { "type": "object", "properties": { "fill": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "border": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "sz": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "color": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "space": { "oneOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "outline": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "shadow": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "emboss": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "imprint": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "charScale": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "kerning": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "vanish": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "webHidden": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "specVanish": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rtl": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "cs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "bCs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "iCs": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "eastAsianLayout": { "oneOf": [ { "type": "object", "properties": { "id": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "combine": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "combineBrackets": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "vert": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "vertCompress": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "em": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "fitText": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "id": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "snapToGrid": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "lang": { "oneOf": [ { "type": "object", "properties": { "val": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsia": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "bidi": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "oMath": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "rStyle": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "rFonts": { "oneOf": [ { "type": "object", "properties": { "ascii": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hAnsi": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsia": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "cs": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "asciiTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hAnsiTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "eastAsiaTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "csTheme": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "hint": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, { "type": "null" } ] }, "fontSizeCs": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "ligatures": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numForm": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "numSpacing": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "stylisticSets": { "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "val": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false }, "minItems": 1 }, { "type": "null" } ] }, "contextualAlternates": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false, "minProperties": 1 }, "alignment": { "type": "string", "enum": [ "left", "center", "right", "justify" ], "description": "Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step." }, "scope": { "type": "string", "enum": [ "match", "block" ], "description": "When \"block\", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use \"block\" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: \"match\"." } }, "additionalProperties": false, "minProperties": 1 } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "op": { "const": "assert", "type": "string" }, "where": { "type": "object", "properties": { "by": { "const": "select", "type": "string" }, "select": { "oneOf": [ { "type": "object", "properties": { "type": { "const": "text", "description": "Must be 'text' for text pattern search." }, "pattern": { "type": "string", "description": "Text to match. In regex mode, patterns are validated for syntax, maximum length, and safety before execution." }, "mode": { "enum": [ "contains", "regex" ], "description": "Match mode: 'contains' (literal substring, recommended for literal text) or 'regex' (validated regular expression)." }, "caseSensitive": { "type": "boolean", "description": "Case-sensitive matching. Default: false." }, "wholeWord": { "type": "boolean", "description": "Require word-boundary matches. Default: false." } }, "additionalProperties": false, "required": [ "type", "pattern" ] }, { "type": "object", "properties": { "type": { "const": "node", "description": "Must be 'node' for node type search." }, "nodeType": { "enum": [ "paragraph", "heading", "listItem", "table", "tableRow", "tableCell", "tableOfContents", "image", "sdt", "run", "bookmark", "comment", "hyperlink", "footnoteRef", "endnoteRef", "crossRef", "indexEntry", "citation", "authorityEntry", "sequenceField", "tab", "lineBreak" ], "description": "Block type to match (paragraph, heading, table, listItem, etc.)." }, "kind": { "enum": [ "block", "inline" ], "description": "Filter: 'block' or 'inline'." } }, "additionalProperties": false, "required": [ "type" ] } ] }, "within": { "$ref": "#/$defs/BlockNodeAddress" } }, "additionalProperties": false, "required": [ "by", "select" ] }, "args": { "type": "object", "properties": { "expectCount": { "type": "number" } }, "additionalProperties": false, "required": [ "expectCount" ] } }, "additionalProperties": false, "required": [ "id", "op", "where", "args" ] } ] }, "description": "Ordered array of mutation steps. Each step needs 'op' (text.rewrite, text.insert, text.delete, format.apply, or assert) and a 'where' targeting clause." } }, "additionalProperties": false, "required": [ "atomic", "changeMode", "steps" ] } ``` ## Output schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$defs": {}, "type": "object", "properties": { "evaluatedRevision": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object" } }, "valid": { "type": "boolean" }, "failures": { "type": "array", "items": { "type": "object" } } }, "additionalProperties": false, "required": [ "evaluatedRevision", "steps", "valid" ] } ``` ## Pre-apply throws - `REVISION_MISMATCH` - `MATCH_NOT_FOUND` - `AMBIGUOUS_MATCH` - `STYLE_CONFLICT` - `PRECONDITION_FAILED` - `INVALID_INPUT` - `CROSS_BLOCK_MATCH` - `SPAN_FRAGMENTED` - `TARGET_MOVED` - `PLAN_CONFLICT_OVERLAP` - `INVALID_STEP_COMBINATION` - `REVISION_CHANGED_SINCE_COMPILE` - `INVALID_INSERTION_CONTEXT` - `DOCUMENT_IDENTITY_CONFLICT` - `CAPABILITY_UNAVAILABLE` - `STORY_NOT_FOUND` - `STORY_MISMATCH` - `STORY_NOT_SUPPORTED` - `CROSS_STORY_PLAN` - `MATERIALIZATION_FAILED` ## Non-applied receipt codes - None