{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-comparison-schema.json",
  "title": "Comparison",
  "description": "One comparison. `status` is the public five, never the stored spelling.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/vaquill-ai-comparisons-api-openapi.yml#/components/schemas/Comparison",
  "properties": {
    "id": {
      "type": "string",
      "title": "Id",
      "description": "Public identifier, `cmp_` followed by 32 hex characters."
    },
    "matterId": {
      "type": "string",
      "title": "Matterid",
      "description": "`mat_` identifier of the matter this comparison belongs to."
    },
    "title": {
      "type": "string",
      "title": "Title",
      "description": "Display title for the comparison."
    },
    "status": {
      "$ref": "#/$defs/OperationStatus",
      "description": "Comparison status, using the same five public values as an operation. Hunks are only complete once this is `succeeded`."
    },
    "original": {
      "$ref": "#/$defs/ComparisonSource",
      "description": "The original side, as resolved at launch."
    },
    "revised": {
      "$ref": "#/$defs/ComparisonSource",
      "description": "The revised side, as resolved at launch."
    },
    "settings": {
      "$ref": "#/$defs/ComparisonSettings",
      "description": "The settings this comparison actually ran with."
    },
    "hunkCount": {
      "type": "integer",
      "title": "Hunkcount",
      "description": "Total structural changes found, cosmetic ones included."
    },
    "substantiveCount": {
      "type": "integer",
      "title": "Substantivecount",
      "description": "Changes the engine judged substantive rather than cosmetic. This is the number a reviewer actually has to look at."
    },
    "summary": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Summary",
      "description": "Prose summary of what changed. Absent until the comparison succeeds."
    },
    "summaryBullets": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Summarybullets",
      "description": "The same summary as discrete points, for rendering as a list."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "title": "Createdat",
      "description": "When the comparison was created (RFC 3339)."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "title": "Updatedat",
      "description": "When the comparison was last updated (RFC 3339)."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "id",
    "matterId",
    "title",
    "status",
    "original",
    "revised",
    "settings",
    "hunkCount",
    "substantiveCount",
    "createdAt",
    "updatedAt"
  ],
  "$defs": {
    "ComparisonSettings": {
      "properties": {
        "granularity": {
          "type": "string",
          "enum": [
            "word",
            "sentence",
            "character"
          ],
          "title": "Granularity",
          "description": "How finely to diff. `word` is the readable default; `character` catches punctuation edits but produces far more hunks.",
          "default": "word"
        },
        "ignoreCase": {
          "type": "boolean",
          "title": "Ignorecase",
          "description": "Treat differences in letter case as unchanged.",
          "default": false
        },
        "ignoreWhitespace": {
          "type": "boolean",
          "title": "Ignorewhitespace",
          "description": "Treat differences in spacing and line breaks as unchanged. On by default, since reflowed paragraphs otherwise dominate the result.",
          "default": true
        },
        "ignoreNumbering": {
          "type": "boolean",
          "title": "Ignorenumbering",
          "description": "Treat renumbered clauses as unchanged. Useful when a clause was inserted and everything below it shifted.",
          "default": false
        },
        "ignoreFormatting": {
          "type": "boolean",
          "title": "Ignoreformatting",
          "description": "Treat bold, italic and font changes as unchanged.",
          "default": false
        },
        "compareTables": {
          "type": "boolean",
          "title": "Comparetables",
          "description": "Include table contents in the comparison.",
          "default": true
        },
        "compareFootnotes": {
          "type": "boolean",
          "title": "Comparefootnotes",
          "description": "Include footnotes in the comparison.",
          "default": true
        },
        "compareHeadersFooters": {
          "type": "boolean",
          "title": "Compareheadersfooters",
          "description": "Include page headers and footers in the comparison.",
          "default": true
        },
        "authorLabel": {
          "type": "string",
          "maxLength": 100,
          "minLength": 1,
          "title": "Authorlabel",
          "description": "Name shown as the revision author on every tracked change in an exported redline. Set it to your own firm or product name."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "title": "ComparisonSettings",
      "description": "How the diff engine treats the two inputs.\n\nA `WorkspaceRequest` even though it is also read back, so `extra=\"forbid\"`\nrefuses an unknown knob on the way in rather than accepting and ignoring it.\nA silently ignored setting is worse than a rejected one: the customer\nbelieves the comparison honoured it.\n\nReading it back is done by explicit projection in the store and never by\nvalidating the stored JSONB, which also carries the engine and the\ndenormalized playbook fields."
    },
    "ComparisonSource": {
      "properties": {
        "documentId": {
          "type": "string",
          "title": "Documentid",
          "description": "`doc_` identifier of this side's document."
        },
        "filename": {
          "type": "string",
          "title": "Filename",
          "description": "Filename as it was at launch. Recorded rather than looked up, so it stays true after the document is renamed."
        },
        "format": {
          "type": "string",
          "title": "Format",
          "description": "Detected document format, for example `docx` or `pdf`. A plain string: the detector also recognizes `rtf` and `odt`."
        },
        "pageCount": {
          "type": "integer",
          "title": "Pagecount",
          "description": "Pages in this side's document."
        },
        "sizeBytes": {
          "type": "integer",
          "title": "Sizebytes",
          "description": "Size of this side's document in bytes."
        }
      },
      "additionalProperties": false,
      "type": "object",
      "required": [
        "documentId",
        "filename",
        "format",
        "pageCount",
        "sizeBytes"
      ],
      "title": "ComparisonSource",
      "description": "One side of a comparison, as it was resolved at launch.\n\nDenormalized on purpose and read back from the stored row rather than from\nthe document: it records what was compared, which stays true after the\ndocument is renamed or replaced."
    },
    "OperationStatus": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "succeeded",
        "failed",
        "cancelled"
      ],
      "title": "OperationStatus",
      "description": "The public five. There is no sixth, and there are no synonyms.\n\nInternal vocabularies spell terminal success `completed`, `ready`,\n`extracted`, `succeeded` and `fresh`; terminal failure `failed` and `error`;\nqueued `pending`, `queued` and `draft`. All of that is collapsed here by\n`app.workspace_api.adapters.status_map`, which refuses to guess."
    }
  }
}