Skip to main content
Alpha: Document API is currently alpha and subject to breaking changes.

​
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

FieldTypeRequiredDescription
targetSnapshotobject(version=“sd-diff-snapshot/v1”)yes
targetSnapshot.coverageobjectyes
targetSnapshot.coverage.bodytrueyesConstant: true
targetSnapshot.coverage.commentsbooleanyes
targetSnapshot.coverage.headerFootersfalseyesConstant: false
targetSnapshot.coverage.numberingbooleanyes
targetSnapshot.coverage.stylesbooleanyes
targetSnapshot.engineenumyes"super-editor"
targetSnapshot.fingerprintstringyes
targetSnapshot.payloadobjectyes
targetSnapshot.version"sd-diff-snapshot/v1"yesConstant: "sd-diff-snapshot/v1"

​
Example request

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

​
Output fields

FieldTypeRequiredDescription
baseFingerprintstringyes
coverageobjectyes
coverage.bodytrueyesConstant: true
coverage.commentsbooleanyes
coverage.headerFootersfalseyesConstant: false
coverage.numberingbooleanyes
coverage.stylesbooleanyes
engineenumyes"super-editor"
payloadobjectyes
summaryobjectyes
summary.bodyobjectyes
summary.body.hasChangesbooleanyes
summary.changedComponentsenum[]yes
summary.commentsobjectyes
summary.comments.hasChangesbooleanyes
summary.hasChangesbooleanyes
summary.numberingobjectyes
summary.numbering.hasChangesbooleanyes
summary.stylesobjectyes
summary.styles.hasChangesbooleanyes
targetFingerprintstringyes
version"sd-diff-payload/v1"yesConstant: "sd-diff-payload/v1"

​
Example response

{
  "baseFingerprint": "example",
  "coverage": {
    "body": true,
    "comments": true,
    "headerFooters": false,
    "numbering": true,
    "styles": true
  },
  "engine": "super-editor",
  "payload": {},
  "summary": {
    "body": {
      "hasChanges": true
    },
    "changedComponents": [
      "body"
    ],
    "comments": {
      "hasChanges": true
    },
    "hasChanges": true,
    "numbering": {
      "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

{
  "additionalProperties": false,
  "properties": {
    "targetSnapshot": {
      "additionalProperties": false,
      "properties": {
        "coverage": {
          "additionalProperties": false,
          "properties": {
            "body": {
              "const": true,
              "type": "boolean"
            },
            "comments": {
              "type": "boolean"
            },
            "headerFooters": {
              "const": false,
              "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": {
          "const": "sd-diff-snapshot/v1",
          "type": "string"
        }
      },
      "required": [
        "version",
        "engine",
        "fingerprint",
        "coverage",
        "payload"
      ],
      "type": "object"
    }
  },
  "required": [
    "targetSnapshot"
  ],
  "type": "object"
}

{
  "additionalProperties": false,
  "properties": {
    "baseFingerprint": {
      "type": "string"
    },
    "coverage": {
      "additionalProperties": false,
      "properties": {
        "body": {
          "const": true,
          "type": "boolean"
        },
        "comments": {
          "type": "boolean"
        },
        "headerFooters": {
          "const": false,
          "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"
            ],
            "type": "string"
          },
          "type": "array"
        },
        "comments": {
          "additionalProperties": false,
          "properties": {
            "hasChanges": {
              "type": "boolean"
            }
          },
          "required": [
            "hasChanges"
          ],
          "type": "object"
        },
        "hasChanges": {
          "type": "boolean"
        },
        "numbering": {
          "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"
      ],
      "type": "object"
    },
    "targetFingerprint": {
      "type": "string"
    },
    "version": {
      "const": "sd-diff-payload/v1",
      "type": "string"
    }
  },
  "required": [
    "version",
    "engine",
    "baseFingerprint",
    "targetFingerprint",
    "coverage",
    "summary",
    "payload"
  ],
  "type": "object"
}