{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/govtube-us/json-schema/govtube-us-citation-result-schema.json",
  "title": "CitationResult",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/govtube-us-openapi.json#/components/schemas/CitationResult",
  "properties": {
    "status": {
      "type": "string",
      "title": "Status",
      "description": "exact, reanchored, moved or superseded."
    },
    "note": {
      "type": "string",
      "title": "Note"
    },
    "video_id": {
      "type": "string",
      "title": "Video Id"
    },
    "timing_granularity": {
      "type": "string",
      "enum": [
        "word",
        "segment",
        "sentence",
        "turn",
        "chunk",
        "document"
      ],
      "title": "Timing Granularity",
      "description": "word: a gt2./gt1. citation of a moment in a video. document: a gd2./gd1. citation of words in an official transcript, with positions instead of times (ADR 0004).",
      "default": "word"
    },
    "original_start_ms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Original Start Ms",
      "description": "Null exactly when timing_granularity is document (no made-up times)."
    },
    "current_start_ms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Current Start Ms",
      "description": "Null when superseded, or for document citations."
    },
    "original_position": {
      "anyOf": [
        {
          "$ref": "#/$defs/DocumentPosition"
        },
        {
          "type": "null"
        }
      ],
      "description": "document only: where the cited words were when the link was made."
    },
    "current_position": {
      "anyOf": [
        {
          "$ref": "#/$defs/DocumentPosition"
        },
        {
          "type": "null"
        }
      ],
      "description": "document only: where they are now; null when superseded."
    },
    "document_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Document Url",
      "description": "document only: the official document."
    },
    "citation_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Citation Text",
      "description": "document only: ready-to-paste citation, “{words}” {speaker}, {title}, {date}. Daily Compilation of Presidential Documents, {package}. {url}. Null when superseded."
    },
    "certifies": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Certifies",
      "description": "document only: what the citation certifies. The words appear in the official transcript; it does not certify them as spoken (ORTH-177 rule 1)."
    },
    "quoted_text": {
      "type": "string",
      "title": "Quoted Text",
      "description": "The words the link originally cited (normalized). Kept after corrections, except for an unsigned link (signed false) that is superseded: then empty, because GovTube can't confirm words that are no longer in the transcript."
    },
    "signed": {
      "type": "boolean",
      "title": "Signed",
      "description": "True for a gt2./gd2. id: GovTube issued it, so quoted_text, cited_rev and the original time or position are what GovTube recorded. False for an older unsigned gt1./gd1. id (ADR 0005): it still resolves, but only the words found in the current transcript are confirmed.",
      "default": false
    },
    "canonical_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Canonical Id",
      "description": "A signed id for the cited words where they are now (null when superseded, or when the server has no citation key). Share this one instead of an unsigned id."
    },
    "transcript_context": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array",
      "title": "Transcript Context"
    },
    "cited_rev": {
      "type": "integer",
      "title": "Cited Rev",
      "description": "Transcript revision the citation was made from."
    },
    "current_rev": {
      "type": "integer",
      "title": "Current Rev",
      "description": "Transcript revision it was resolved against."
    },
    "corrected_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Corrected At",
      "description": "For reanchored, moved and superseded: the date (UTC) the current revision was published, i.e. the latest correction since the link was made. If current_rev - cited_rev > 1, an earlier revision may have made the change. Null for exact, or when that revision was published before revision dates were recorded."
    },
    "replacement": {
      "anyOf": [
        {
          "$ref": "#/$defs/CitationReplacement"
        },
        {
          "type": "null"
        }
      ],
      "description": "superseded only: where the corrected passage lives. Null when it could not be determined; replacement_note then says so."
    },
    "replacement_note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Replacement Note",
      "description": "superseded only: how the replacement was found, or why it could not be."
    },
    "low_confidence": {
      "type": "boolean",
      "title": "Low Confidence",
      "description": "verification is low_confidence: the quoted words, as they stand in the current transcript, are on hold until reviewed (ORTH-176; same rule as search results). False for superseded (no current words) and document citations.",
      "default": false
    },
    "withheld": {
      "type": "boolean",
      "title": "Withheld",
      "description": "low_confidence and no reviewer has checked these words yet (review state 'unreviewed'). The API still returns the words (quoted_text, transcript_context); the web decides what to hide (share page 'on hold' state).",
      "default": false
    },
    "caption_check": {
      "type": "string",
      "enum": [
        "agrees",
        "differs",
        "not_checked"
      ],
      "title": "Caption Check",
      "description": "How the official live captions compare with the words a quote of this result shows: the excerpt and the whole sentence(s) around the matched words, not just the matched words (ORTH-225; HEURISTIC). differs: the captions have different words somewhere in there, so the machine transcript may have misheard them; check the video before quoting and say the transcript is unverified. agrees: the captions have the same words (captions are live stenography, not a verbatim record, so this is not a check by a person). not_checked: no caption check for this video, the captions skip some of these words, or an official transcript (no captions to compare). Always not_checked when superseded (no current words) and for document citations.",
      "default": "not_checked"
    },
    "verification": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "checked",
            "unverified",
            "low_confidence"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Verification",
      "description": "Whether the words a quote of this result shows (the excerpt and the sentence(s) around the matched words, as caption_check) were checked against a second source (ORTH-176). checked: the official captions have the same words, or a reviewer checked them; no mark is shown. unverified: nothing to check them against, or the captions differ where the speech recognizer was sure of its words (the captioner's spelling or mishearing, more often than not); say 'Transcript unverified'. low_confidence: on hold until reviewed; a caption difference where the recognizer's own word score was under 0.9, or a word scored under 0.5 that the captions can't check (HEURISTIC thresholds, not yet calibrated by listening). Null for official documents (no machine transcript). Null when superseded (no current words)."
    },
    "verification_source": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "house_captions",
            "senate_captions",
            "dvids_captions",
            "reviewer",
            "asr_word_confidence"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Verification Source",
      "description": "What checked or disputed the words: house_captions, senate_captions, dvids_captions (the official live captions), reviewer (a person, against the video) or asr_word_confidence (the recognizer's own word score; low_confidence only). Null when unverified."
    },
    "words_checked": {
      "type": "boolean",
      "title": "Words Checked",
      "description": "A reviewer checked the cited words against the video (review state confirmed or corrected). False (every citation today): the words are a machine transcript nobody has checked, so end a quoted citation with 'Transcript unverified.' Always false for document citations (they cite an official transcript).",
      "default": false
    },
    "source_certainty": {
      "type": "string",
      "enum": [
        "official_record",
        "official_channel",
        "unverified"
      ],
      "title": "Source Certainty",
      "description": "The cited video's. How sure GovTube is about the source material (ADR 0006). official_record: the official recording or record of the proceeding (House and Senate video, the Daily Compilation of Presidential Documents). official_channel: published by the office itself, e.g. on its official YouTube channel; it may be edited or excerpted and is not the complete record. unverified: not confirmed as official. Show source_caveats whenever this is not official_record or source_caveats is not empty.",
      "default": "unverified"
    },
    "source_caveats": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Source Caveats",
      "description": "The cited video's. Plain sentences about what is uncertain in this source material, to show (and pass along) with any quote, e.g. 'Speakers are identified by machine and not reviewed.' Empty when there is nothing to add."
    }
  },
  "type": "object",
  "required": [
    "status",
    "note",
    "video_id",
    "original_start_ms",
    "current_start_ms",
    "quoted_text",
    "cited_rev",
    "current_rev"
  ],
  "$defs": {
    "CitationReplacement": {
      "properties": {
        "video_id": {
          "type": "string",
          "title": "Video Id"
        },
        "start_ms": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Start Ms",
          "description": "Null exactly when timing_granularity is document (no made-up times)."
        },
        "end_ms": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "End Ms",
          "description": "Null exactly when timing_granularity is document (no made-up times)."
        },
        "play_from_ms": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Play From Ms",
          "description": "Playback start including pre-roll, in playback-asset time. Null exactly when timing_granularity is document (no made-up times)."
        },
        "position": {
          "anyOf": [
            {
              "$ref": "#/$defs/DocumentPosition"
            },
            {
              "type": "null"
            }
          ],
          "description": "document only: where the replacement words start."
        },
        "text": {
          "type": "string",
          "title": "Text",
          "description": "The current words at the cited time or position (HEURISTIC: same place, not proven to be the same remark)."
        }
      },
      "type": "object",
      "required": [
        "video_id",
        "start_ms",
        "end_ms",
        "play_from_ms",
        "text"
      ],
      "title": "CitationReplacement",
      "description": "Where a superseded citation's moment (or, in an official document, position) lives now."
    },
    "DocumentPosition": {
      "properties": {
        "paragraph": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Paragraph",
          "description": "Paragraph of the transcript text, from 1. The document's heading, date line and closing note are not counted."
        },
        "word": {
          "type": "integer",
          "minimum": 1.0,
          "title": "Word",
          "description": "Word within that paragraph, from 1. Words are separated by spaces; the speaker label such as 'The President.' is not counted, a stage note such as '[Applause]' is."
        }
      },
      "type": "object",
      "required": [
        "paragraph",
        "word"
      ],
      "title": "DocumentPosition",
      "description": "Where words sit in an official document's transcript text (ADR 0004), counted from 1 as a reader counts."
    }
  }
}