{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/vaquill-ai/json-schema/vaquill-ai-comparison-create-request-schema.json",
  "title": "ComparisonCreateRequest",
  "description": "Start a comparison between two documents already in the matter.\n\nBoth sides are matter documents. The internal API also accepts drafts,\ndraft versions and loose uploads; publishing those would mean publishing\nthree more identifier spaces, and a customer that wants to compare arbitrary\nbytes uploads them to the matter first, which is one call it was going to\nmake anyway.\n\nThere is no `matterId` field. The matter is the path, which is what makes\nthe authorization boundary visible in the URL.",
  "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/ComparisonCreateRequest",
  "properties": {
    "title": {
      "type": "string",
      "maxLength": 300,
      "minLength": 1,
      "title": "Title",
      "description": "Display title for the comparison. Trimmed; whitespace alone is refused."
    },
    "originalDocumentId": {
      "type": "string",
      "title": "Originaldocumentid",
      "description": "`doc_` identifier of the ORIGINAL document, the one being compared against. Must be in this matter."
    },
    "revisedDocumentId": {
      "type": "string",
      "title": "Reviseddocumentid",
      "description": "`doc_` identifier of the REVISED document. Must be in this matter, and must differ from `originalDocumentId`."
    },
    "settings": {
      "$ref": "#/$defs/ComparisonSettings",
      "description": "How the diff engine should treat the two inputs. Omit for sensible defaults."
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "title",
    "originalDocumentId",
    "revisedDocumentId"
  ],
  "$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."
    }
  }
}