diff.compare

Compare the current document (base) against a previously captured target snapshot. Returns a versioned diff payload describing the changes from base to target.

Summary

Compare the current document (base) against a previously captured target snapshot. Returns a versioned diff payload describing the changes from base to target.

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

Expected result

Returns a DiffPayload with a summary and opaque payload.

Input fields

Field	Type	Required	Description
targetSnapshot	object	yes
targetSnapshot.coverage	object	yes
targetSnapshot.coverage.body	true	yes	Constant: true
targetSnapshot.coverage.comments	boolean	yes
targetSnapshot.coverage.headerFooters	boolean	yes
targetSnapshot.coverage.numbering	boolean	yes
targetSnapshot.coverage.styles	boolean	yes
targetSnapshot.engine	enum	yes	"super-editor"
targetSnapshot.fingerprint	string	yes
targetSnapshot.payload	object	yes
targetSnapshot.version	enum	yes	"sd-diff-snapshot/v1", "sd-diff-snapshot/v2"

Example request

{
  "targetSnapshot": {
    "coverage": {
      "body": true,
      "comments": true,
      "headerFooters": true,
      "numbering": true,
      "styles": true
    },
    "engine": "super-editor",
    "fingerprint": "example",
    "payload": {},
    "version": "sd-diff-snapshot/v1"
  }
}

Output fields

Field	Type	Required	Description
baseFingerprint	string	yes
coverage	object	yes
coverage.body	true	yes	Constant: true
coverage.comments	boolean	yes
coverage.headerFooters	boolean	yes
coverage.numbering	boolean	yes
coverage.styles	boolean	yes
engine	enum	yes	"super-editor"
payload	object	yes
summary	object	yes
summary.body	object	yes
summary.body.hasChanges	boolean	yes
summary.changedComponents	enum[]	yes
summary.comments	object	yes
summary.comments.hasChanges	boolean	yes
summary.hasChanges	boolean	yes
summary.headerFooters	object	yes
summary.headerFooters.hasChanges	boolean	yes
summary.numbering	object	yes
summary.numbering.hasChanges	boolean	yes
summary.parts	object	yes
summary.parts.hasChanges	boolean	yes
summary.styles	object	yes
summary.styles.hasChanges	boolean	yes
targetFingerprint	string	yes
version	enum	yes	"sd-diff-payload/v1", "sd-diff-payload/v2"

Example response

{
  "baseFingerprint": "example",
  "coverage": {
    "body": true,
    "comments": true,
    "headerFooters": true,
    "numbering": true,
    "styles": true
  },
  "engine": "super-editor",
  "payload": {},
  "summary": {
    "body": {
      "hasChanges": true
    },
    "changedComponents": [
      "body"
    ],
    "comments": {
      "hasChanges": true
    },
    "hasChanges": true,
    "headerFooters": {
      "hasChanges": true
    },
    "numbering": {
      "hasChanges": true
    },
    "parts": {
      "hasChanges": true
    },
    "styles": {
      "hasChanges": true
    }
  },
  "targetFingerprint": "example",
  "version": "sd-diff-payload/v1"
}

Pre-apply throws

• INVALID_INPUT
• CAPABILITY_UNSUPPORTED

Non-applied failure codes

• None

Raw schemas

Raw input schema

{
  "additionalProperties": false,
  "properties": {
    "targetSnapshot": {
      "additionalProperties": false,
      "properties": {
        "coverage": {
          "additionalProperties": false,
          "properties": {
            "body": {
              "const": true,
              "type": "boolean"
            },
            "comments": {
              "type": "boolean"
            },
            "headerFooters": {
              "type": "boolean"
            },
            "numbering": {
              "type": "boolean"
            },
            "styles": {
              "type": "boolean"
            }
          },
          "required": [
            "body",
            "comments",
            "styles",
            "numbering",
            "headerFooters"
          ],
          "type": "object"
        },
        "engine": {
          "enum": [
            "super-editor"
          ],
          "type": "string"
        },
        "fingerprint": {
          "type": "string"
        },
        "payload": {
          "description": "Opaque engine-owned snapshot data.",
          "type": "object"
        },
        "version": {
          "enum": [
            "sd-diff-snapshot/v1",
            "sd-diff-snapshot/v2"
          ],
          "type": "string"
        }
      },
      "required": [
        "version",
        "engine",
        "fingerprint",
        "coverage",
        "payload"
      ],
      "type": "object"
    }
  },
  "required": [
    "targetSnapshot"
  ],
  "type": "object"
}

Raw output schema

{
  "additionalProperties": false,
  "properties": {
    "baseFingerprint": {
      "type": "string"
    },
    "coverage": {
      "additionalProperties": false,
      "properties": {
        "body": {
          "const": true,
          "type": "boolean"
        },
        "comments": {
          "type": "boolean"
        },
        "headerFooters": {
          "type": "boolean"
        },
        "numbering": {
          "type": "boolean"
        },
        "styles": {
          "type": "boolean"
        }
      },
      "required": [
        "body",
        "comments",
        "styles",
        "numbering",
        "headerFooters"
      ],
      "type": "object"
    },
    "engine": {
      "enum": [
        "super-editor"
      ],
      "type": "string"
    },
    "payload": {
      "description": "Opaque engine-owned diff data.",
      "type": "object"
    },
    "summary": {
      "additionalProperties": false,
      "properties": {
        "body": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        },
        "changedComponents": {
          "items": {
            "enum": [
              "body",
              "comments",
              "styles",
              "numbering",
              "headerFooters",
              "parts"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "comments": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        },
        "hasChanges": {
          "type": "boolean"
        },
        "headerFooters": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        },
        "numbering": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        },
        "parts": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        },
        "styles": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        }
      },
      "required": [
        "hasChanges",
        "changedComponents",
        "body",
        "comments",
        "styles",
        "numbering",
        "headerFooters",
        "parts"
      ],
      "type": "object"
    },
    "targetFingerprint": {
      "type": "string"
    },
    "version": {
      "enum": [
        "sd-diff-payload/v1",
        "sd-diff-payload/v2"
      ],
      "type": "string"
    }
  },
  "required": [
    "version",
    "engine",
    "baseFingerprint",
    "targetFingerprint",
    "coverage",
    "summary",
    "payload"
  ],
  "type": "object"
}