{
  "id": 11446182,
  "title": "Why a VEX document should be diffed claim by claim",
  "url": "https://urgent.news/2026/10/02/why-a-vex-document-should-be-diffed-claim-by-claim",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-02T13:23:34.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/polycratia/why-a-vex-document-should-be-diffed-claim-by-claim-56id"
  },
  "original_language": "en",
  "account": "A VEX document should be diffed claim by claim for several reasons. Firstly, a customer only reads the first published VEX document and the differences between it and subsequent versions. If the tooling cannot produce these differences, each downstream reader must re-triage the entire document, which is not ideal. The EU Cyber Resilience Act expects manufacturers to provide a quick and written response to the \"are you affected\" question for every product they ship, making the delta (the difference) the deliverable.\n\nSecondly, a VEX document is JSON, so the straightforward approach is to diff two copies with an existing tool. However, this method reports byte-level changes, not claim-level changes. For instance, adding a component to the inventory and regenerating the document results in deletions and insertions, making it difficult to discern if there were no actual changes. The genuine matter is not textually large; for example, a conclusion that stays 'not_affected' but now rests on a different justification is a one-token edit hidden within a wall of moved lines.\n\nTo address this issue, a VEX diff should have a keyed comparison, where unmatched items are promoted to the top of the report. This approach allows identifying new claims, restated claims, and rejustified claims. A new claim is identified by a key present in one document but absent in the other. A restated claim appears in both documents with a different status, while a rejustified claim is present in both documents with the same status but a different justification.\n\nThe first decision when diffing VEX documents is identifying a claim, which is not the statement object but the pair: a vulnerability against a product. This pair is the key both documents are indexed by, and the rest of the document's structure (ordering, timestamps, etc.) is serialisation. Once comparison is keyed, the vocabulary of changes naturally falls out of it. For example, a key present now and absent before is a new claim; a key present on both sides with a different status is a restated claim; and a key present on both sides with the same status but a different justification is a rejustified claim.\n\nA key advantage of this approach is that it makes the report concise and easy to understand. Instead of showing all four unchanged claims, the report simply states that \"four claims are unchanged.\" Additionally, a customer is less likely to read through the document if the changes are presented as only three rows instead of a wall of moved lines.\n\nFurthermore, a rejustified row is crucial, as it represents a claim that held for a new reason. For instance, a status-only comparison might drop this row, but it is still a different claim. The justification represents the claim's argument, and a reviewer accepted the argument, not the word. Therefore, a rejustified row deserves its own change class and its own row in the report.\n\nIn conclusion, diffing VEX documents claim by claim provides a more accurate and efficient way to compare documents. It focuses on the essential changes, such as new, restated, and rejustified claims, and ignores cosmetic differences in statement order. This approach also helps security reviewers identify when their earlier reviews no longer cover what the document now asserts, ensuring that the document remains relevant and up-to-date.",
  "summary": "Nobody reads your VEX document twice. A customer reads the first one you publish, and after that they read the difference between the new one and the copy they already hold: which advisories you have newly admitted, which conclusions you changed, which ones you have closed. If your tooling cannot produce that difference, every release asks each downstream reader to re-triage a whole document from…",
  "key_points": [
    "Diff VEX documents claim by claim for customer readability",
    "VEX document is JSON, straightforward diff reports byte-level changes",
    "Keyed comparison promotes unmatched items to top of report"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}