{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nexusquantum-legal/json-schema/nexusquantum-legal-verificacion-response-schema.json",
  "title": "VerificacionResponse",
  "description": "Result of the Verification Center over one document.\n\n🔴 THE HEADLINE COUNTERS ARE NOT A VERDICT. `found` counts every citation that EXISTS in the corpus, including the ones carrying a reproach — deliberately, because the statement \"this citation exists\" stays true when it resolves to another decision. So a document whose only citation names the wrong court comes back `found: 1, not_found: 0`. Read `review_required` (or the `X-Nexus-Verification` response header) first, and `verified_clean` / `flagged` instead of `found` when you need the clean count.\n\nInvariant: `found === verified_clean + flagged`.",
  "x-generated": "2026-11-19",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nexusquantum-legal-openapi.json#/components/schemas/VerificacionResponse",
  "type": "object",
  "required": [
    "fecha",
    "total",
    "found",
    "not_found",
    "derogated",
    "unknown",
    "results",
    "flagged",
    "verified_clean",
    "review_required",
    "counts_by_meaning",
    "verifiable_jurisdictions",
    "citations_detected",
    "citations_checked"
  ],
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "English twin of `fecha`. Either works; neither is retired."
    },
    "fecha": {
      "type": "string",
      "format": "date",
      "description": "Date the force-status was evaluated at (YYYY-MM-DD)."
    },
    "total": {
      "type": "integer",
      "description": "Citations actually checked (same value as `citations_checked`)."
    },
    "found": {
      "type": "integer",
      "description": "Citations that EXIST in the corpus — flagged ones INCLUDED. Not the clean count: that is `verified_clean`."
    },
    "not_found": {
      "type": "integer",
      "description": "Citations absent from the active corpus."
    },
    "derogated": {
      "type": "integer",
      "description": "Citations that existed but are not in force on `fecha`."
    },
    "unknown": {
      "type": "integer",
      "description": "Citations that could not be checked. A gap, not a pass."
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/VerificacionResult"
      }
    },
    "flagged": {
      "type": "integer",
      "description": "Citations that exist but carry a reproach: rows with `results[i].meaning` PLUS rows with `results[i].party_check === \"partial\"` (identity half-confirmed, which has no `meaning`). They resolve to another decision, distort the text, are unverifiable paraphrases, or name a party that does not appear in the decision."
    },
    "verified_clean": {
      "type": "integer",
      "description": "`found` minus `flagged`: the citations that came back clean. This is the number to show as \"verified\"."
    },
    "review_required": {
      "type": "boolean",
      "description": "The one question an integrator asks: can I proceed without looking? `false` ONLY when nothing is flagged, nothing is missing, nothing is derogated, nothing was uncheckable and nothing fell outside the per-request cap. A gap counts as a reason to look: \"could not be checked\" is not \"is fine\". Mirrored on every response in the `X-Nexus-Verification` header (`review-required` | `clean`) so you can branch without parsing the body."
    },
    "counts_by_meaning": {
      "type": "object",
      "description": "Breakdown of the `meaning` reproaches ONLY, so `other_case + diverges + paraphrase` is **≤ `flagged`**, not equal to it: the difference is the identity-half-confirmed rows (`party_check: \"partial\"`), which carry no `meaning`, so do not reconcile this breakdown against `flagged`. Always present; zeros are real zeros.",
      "required": [
        "other_case",
        "diverges",
        "paraphrase"
      ],
      "properties": {
        "other_case": {
          "type": "integer",
          "description": "Citations that resolve to a DIFFERENT decision from the one named."
        },
        "diverges": {
          "type": "integer",
          "description": "Citations whose attributed sense diverges from the official text."
        },
        "paraphrase": {
          "type": "integer",
          "description": "Citations that could not be checked literally (paraphrase or assembled quotation)."
        }
      }
    },
    "verifiable_jurisdictions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Jurisdictions with a verifier wired up TODAY. Always declared, so a `total: 0` can be checked against your own jurisdiction instead of being read as \"clean document\"."
    },
    "citations_detected": {
      "type": "integer",
      "description": "Citations FOUND in the document."
    },
    "citations_checked": {
      "type": "integer",
      "description": "Citations actually CHECKED (== `total`). Compare it with `citations_detected`: when they differ, the per-request cap applied."
    },
    "citations_truncated": {
      "type": "object",
      "description": "Present ONLY when the per-request cap (100 citations) cut the document short. The unchecked citations do NOT appear in `results` at all, and their absence is not a clean bill of health — split the document and send it in parts.",
      "required": [
        "code",
        "limit",
        "detected",
        "checked",
        "unchecked",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "CITATION_LIMIT_REACHED"
          ],
          "description": "Machine contract: branch on this, not on the prose."
        },
        "limit": {
          "type": "integer"
        },
        "detected": {
          "type": "integer"
        },
        "checked": {
          "type": "integer"
        },
        "unchecked": {
          "type": "integer"
        },
        "message": {
          "type": "string",
          "description": "English explanation for the integrator's on-call human. The UI renders its own translated notice."
        }
      }
    },
    "text_truncated": {
      "type": "boolean",
      "description": "Present (and always `true`) when the document exceeded 50,000 characters and only the first 50,000 were analysed: the citations in the remainder were NOT looked at and appear nowhere in this response — their absence from `results` is not a clean bill of health. Absent otherwise. Without this field a 90-page brief comes back the same shape as one reviewed in full."
    },
    "requestId": {
      "type": "string",
      "description": "Same value as the `X-Request-Id` response header. Quote it in support."
    }
  },
  "$defs": {
    "VerificacionResult": {
      "type": "object",
      "description": "One citation found in the document, with its verdict.\n\n🔴 READ `status` AND `meaning` TOGETHER. `status: \"found\"` means THE CITATION EXISTS in the corpus — it does NOT mean the citation is sound. When `meaning` is present the row carries a REPROACH and is not a clean citation; the aggregate of those rows is `flagged` on the response. A client that colours or branches on `status` alone will paint a citation that resolves to a different decision as verified.",
      "required": [
        "raw",
        "alias",
        "norma_label",
        "numero_articulo",
        "status",
        "canonical_text",
        "canonical_truncated",
        "url",
        "context",
        "kind"
      ],
      "properties": {
        "raw": {
          "type": "string",
          "description": "The citation exactly as it appears in the document."
        },
        "alias": {
          "type": [
            "string",
            "null"
          ],
          "description": "Recognised alias of the piece of legislation (ES/BOE pass), e.g. `CC`, `LEC`. `null` for case law and for citations resolved by the jurisdiction-agnostic pass."
        },
        "norma_label": {
          "type": [
            "string",
            "null"
          ],
          "description": "Human-readable name of the legislation behind `alias`. `null` when there is no alias."
        },
        "numero_articulo": {
          "type": "string",
          "description": "Article/section number, when the citation carries one. Empty string when it does not (a whole statute, or a judgment)."
        },
        "status": {
          "type": "string",
          "enum": [
            "found",
            "not_found",
            "derogated",
            "unknown"
          ],
          "description": "`found` = the citation EXISTS in the corpus of its jurisdiction. It is NOT a clean bill of health on its own: check `meaning`. `not_found` = it is absent from the active corpus. `derogated` = it existed but is not in force on `fecha`. `unknown` = it could not be checked (see `unknown_reason`) — a gap, never a pass. This enum is CLOSED and stays at four values: everything added since travels in additive optional fields, so a `switch` written against it keeps compiling. The price of that promise is that the enum cannot tell you the whole verdict by itself."
        },
        "content_checked": {
          "type": "boolean",
          "enum": [
            false
          ],
          "description": "PRESENT AND `false` = the verdict establishes that the provision EXISTS, and the WORDING your document attributes to it was never compared against the official text. ABSENT = the content was compared (or the comparison does not apply). The field only appears when there is something to warn about, so `content_checked === false` is the test, not its truthiness. This is the case for the whole of the United Kingdom, where content comparison is deliberately not enabled. It is the difference between «this section exists» and «this section says what you claim», which for a citation-checking product is the whole distinction."
        },
        "meaning": {
          "type": "string",
          "enum": [
            "other_case",
            "diverges",
            "paraphrase"
          ],
          "description": "REPROACH on a citation that exists (so `status` is `found`). PRESENT ⇒ the row is flagged. **ABSENT DOES NOT MEAN CLEAN**: a row can be flagged by `party_check: \"partial\"` with no `meaning` at all. The exact predicate is `status === \"found\" && (meaning || party_check === \"partial\")`.\n\n`other_case` — the citation EXISTS but resolves to a DIFFERENT decision from the one the document names (incompatible party names, typically a transposed court: `Spandeck … [2007] SGHC 37` where the case is `[2007] SGCA 37`). NOTHING WAS COMPARED about the sense of the quotation: the defect is the IDENTITY of the authority, and `similarity` is deliberately left unmeasured. Do not present it as a paraphrase — it points somewhere else. `note` names the decision it actually resolves to and, when found, the sibling citation that does match.\n`diverges` — a meaning veto fired against the official text (negation, modality, quantifier, omitted exception, subject): a REAL divergence of sense.\n`paraphrase` — only the lexical ratio failed, or the quoted fragments are literal but assembled from non-continuous passages. A divergence of meaning has NOT been proven; it could not be checked literally. Use `mismatch_kind` to tell the two apart.\n\nEarlier versions of this document described the field as appearing \"when the citation exists but the attributed sense does not match\" and listed only two values. That was false for `other_case`, where no sense is compared at all."
        },
        "vigencia_desde": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "Date the provision came into force, when the verifier measured in-force status unambiguously. Present on `derogated` rows (ES/CO always; UK legislation, repealed or not-yet-in-force alike) and on UK `found` rows confirmed currently in force. Absent = in-force status not measured for this row — never read absence as \"in force with no known date\"."
        },
        "vigencia_hasta": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "Date the provision ceased to be in force (repeal date). Present only when the row is `derogated` for having been repealed — absent for a provision that never yet came into force."
        },
        "party_check": {
          "type": [
            "string",
            "null"
          ],
          "description": "State of the PARTY-NAME contrast, where the jurisdiction performs one. Values are ADDITIVE and the list is OPEN: `match` · `no_name` · `unavailable` · `mismatch` · `partial`. Treat an unknown value as FLAGGED, never as clean.\n\n🔴 `partial` FLAGS THE ROW ON ITS OWN, WITHOUT `meaning`. It means: the decision exists, but a party the document names appears neither in the name the record gives that decision nor in its text — identity half-confirmed. It does NOT assert the citation is wrong (the record may list only the lead party; you may be using an acronym; it may be a joined appeal) and it does NOT confirm it either. `note` carries the reason in prose.\n\nTravels separately from `meaning` deliberately: «a party you name does not appear» is NOT «resolves to another decision», and asserting the latter would be a reproach we cannot sustain."
        },
        "mismatch_kind": {
          "type": "string",
          "enum": [
            "lexical",
            "meaning",
            "stitched",
            "party"
          ],
          "description": "The engine's reproach VERBATIM, before `meaning` collapses it. `stitched` and `lexical` both map to `meaning: \"paraphrase\"`, so without this field the two are indistinguishable on the wire and a formatter has to guess which one it is holding.\n\n`party` → `meaning: \"other_case\"`. `meaning` → `meaning: \"diverges\"`. `stitched` (literal fragments assembled from non-continuous passages, or reordered) and `lexical` (ratio only) → `meaning: \"paraphrase\"`. ADDITIVE and open to growth: treat an unrecognised value as flagged, never as clean."
        },
        "canonical_text": {
          "type": [
            "string",
            "null"
          ],
          "description": "Official text the citation was checked against, trimmed to what is worth reading. `null` when the corpus returned no text."
        },
        "canonical_truncated": {
          "type": "boolean",
          "description": "`true` when `canonical_text` stops short of the full official text: the rest of the article or judgment exists but is NOT written in this response. Do not read the excerpt as the whole provision, and do not conclude from it that the citation covers nothing else. `false` asserts the official text travels whole."
        },
        "url": {
          "type": [
            "string",
            "null"
          ],
          "description": "Official source URL for that jurisdiction when one is located (BOE · CENDOJ · Singapore Statutes Online · eLitigation · SUIN-Juriscol…)."
        },
        "context": {
          "type": "string",
          "description": "The surrounding sentence of the document, so the citation can be located without the source file."
        },
        "kind": {
          "type": "string",
          "enum": [
            "norma",
            "jurisprudencia"
          ],
          "description": "What was cited: legislation or case law. Without it a judgment gets reported as an \"article not found in the corpus\", which is a category error on top of the finding."
        },
        "note": {
          "type": [
            "string",
            "null"
          ],
          "description": "Deterministic, server-side explanation of the verdict — never model prose. THE MOST ACTIONABLE PART OF A FLAGGED ROW: it says which decision the citation actually resolves to, and where the correct citation is. Render it; do not drop it."
        },
        "unknown_reason": {
          "type": "string",
          "enum": [
            "not_verifiable",
            "error"
          ],
          "description": "Why the row is `unknown`. `not_verifiable` = no corpus is wired up for that jurisdiction/alias — a stable property of coverage you can decide with. `error` = the check ran and broke — ours, and worth retrying. Neither is a pass."
        }
      }
    }
  }
}