{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://claimset.org/schema/1/claims.schema.json",
  "title": "claimset claims file",
  "description": "A register of published claims, each pinned to the verbatim span of a primary source, the date it was checked, and the date the check goes stale. Machine-checkable: a verifier re-fetches every source_url and reports whether the assertion is still there.",
  "type": "object",
  "required": ["claims"],
  "additionalProperties": false,
  "properties": {
    "claimset": {
      "description": "Format version. Absent means \"1\". A verifier MUST refuse a version it does not implement rather than guess.",
      "type": "string",
      "const": "1",
      "default": "1"
    },
    "title": {
      "description": "Human label for this register.",
      "type": "string"
    },
    "publisher": {
      "description": "Who stands behind these claims.",
      "type": "string"
    },
    "contact": {
      "description": "Where to report that a claim is wrong. A URL or an email address.",
      "type": "string"
    },
    "_comment": {
      "description": "Free-text note. Ignored by verifiers.",
      "type": "string"
    },
    "claims": {
      "type": "array",
      "minItems": 1,
      "items": { "$ref": "#/$defs/claim" }
    }
  },
  "$defs": {
    "claim": {
      "type": "object",
      "required": ["claim_id", "assertion", "source_url", "checked_on", "expires_on"],
      "additionalProperties": false,
      "properties": {
        "claim_id": {
          "description": "Stable identifier, unique within the file. Referenced by superseded_by and by any content that cites this claim. Never reuse an id for a different fact.",
          "type": "string",
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
        },
        "assertion": {
          "description": "A VERBATIM span from the source, not a paraphrase and not a summary. It must also be specific enough that finding it in the source is evidence rather than coincidence - but that is a SEMANTIC rule enforced by the verifier (SPEC.md 2.1: status WEAK), not a structural one enforced here. This schema deliberately accepts a weak assertion so that a verifier can report exactly why it is weak, rather than the file failing to parse.",
          "type": "string",
          "minLength": 1
        },
        "source_url": {
          "description": "The primary source the assertion was read from. Prefer the authority that sets the fact over anyone reporting on it. file: is permitted for local fixtures and offline registers.",
          "type": "string",
          "format": "uri",
          "pattern": "^(https?|file)://"
        },
        "checked_on": {
          "description": "The date a human or a verifier last confirmed the assertion appears at source_url.",
          "type": "string",
          "format": "date",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "expires_on": {
          "description": "The date after which this check is stale and the claim must not be presented as current. MUST be after checked_on. This is the field llms.txt and every self-attested freshness badge omits, and it is the whole point: a claim with no expiry never becomes wrong, it just quietly stops being right.",
          "type": "string",
          "format": "date",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "superseded_by": {
          "description": "The claim_id, in this same file, that replaces this one. A superseded claim is reported and skipped, never fetched, and never fails a run. Supersede rather than delete: readers who cite the old id deserve to find out what replaced it.",
          "type": ["string", "null"],
          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
        },
        "source_sha256": {
          "description": "SHA-256 of the raw response body at checked_on, lowercase hex. Advisory: a mismatch means the page changed somewhere, which is reported but does not fail the run unless --strict-source is set, because a page can be edited elsewhere without touching the sentence you cited. Omit it for sources whose bytes vary per request.",
          "type": ["string", "null"],
          "pattern": "^[0-9a-f]{64}$"
        },
        "note": {
          "description": "Free text for humans. Why this claim matters, what to do if it drifts.",
          "type": "string"
        },
        "tags": {
          "description": "Arbitrary labels for grouping claims.",
          "type": "array",
          "items": { "type": "string" }
        }
      }
    }
  },
  "examples": [
    {
      "claimset": "1",
      "publisher": "Denial Facts",
      "claims": [
        {
          "claim_id": "external-review-deadline-four-months",
          "assertion": "you must file a written request for an external review within four months after the date you receive a notice or final determination from your insurer",
          "source_url": "https://www.healthcare.gov/appeal-insurance-company-decision/external-review/",
          "checked_on": "2026-08-14",
          "expires_on": "2027-02-14",
          "source_sha256": "149ad94ef004d0b7356e8343267575e9268921bde714cc1722eb4537d915fc0d"
        }
      ]
    }
  ]
}