{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gxplex.com/api/v1/schema/instruments.json",
  "title": "Tracked document document",
  "description": "The document served at /api/v1/instruments.json. Items are carried under `items`.",
  "type": "object",
  "allOf": [
    {
      "$ref": "https://gxplex.com/api/v1/schema/envelope.json"
    }
  ],
  "properties": {
    "collection": {
      "const": "instruments"
    },
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/item"
      },
      "description": "Every tracked document this document carries."
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": true,
  "$defs": {
    "item": {
      "type": "object",
      "title": "Tracked document",
      "description": "One document this archive observes, with what the record holds about it and the act that produced each published value.",
      "properties": {
        "licence_class": {
          "type": "string",
          "enum": [
            "open",
            "restricted",
            "unknown"
          ],
          "description": "What this archive recorded of the terms the source states. See `rights` on the envelope for what each value means in terms of this archive handling."
        },
        "text_retained": {
          "type": "boolean",
          "description": "Whether normalised prose of the document is held here for a quotation to be checked against."
        },
        "quote_allowed": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether a quotation from the document appears in this record's own published output. A fact about this record's handling, not a reading of what the publisher permits, and not a grant. Null where no reading exists."
        },
        "snapshot_available": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether a retained snapshot of an observed retrieval is still held here for a digest to be re-checked against. No snapshot is served. Null where no reading exists."
        },
        "rights_of": {
          "type": [
            "string",
            "null"
          ],
          "description": "The tracked entry id the four fields above are the rights OF. Null where the object names no entry."
        },
        "rights_unresolved": {
          "type": [
            "string",
            "null"
          ],
          "description": "Present only where the four fields are null, naming which absence it is: an id this record does not hold, or an object that names no entry."
        },
        "id": {
          "type": "string",
          "description": "The identifier this archive records the document under."
        },
        "title": {
          "type": "string",
          "description": "The title the publisher prints."
        },
        "short_title": {
          "type": "string",
          "description": "A shortened form used where a full title does not fit."
        },
        "authority": {
          "type": "string",
          "description": "The body that publishes the document."
        },
        "jurisdiction": {
          "type": "string",
          "description": "The jurisdiction the publishing authority belongs to. A closed enum in the source schema."
        },
        "status": {
          "type": "string",
          "enum": [
            "draft",
            "proposed",
            "final",
            "in-force",
            "superseded",
            "withdrawn",
            "unknown"
          ],
          "description": "The status this record holds for the document. `unknown` is a first-class value: a status nobody has checked is stated as unknown rather than guessed."
        },
        "status_qualifier": {
          "type": [
            "string",
            "null"
          ],
          "description": "A qualifier on the status, or null where none applies. Null after a qualifier is retired, which is a different fact from one never written."
        },
        "status_as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The day the status is stated as of. Never a date an obligation begins."
        },
        "last_verified": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The day a person confirmed the status. Null where no person has."
        },
        "last_changed": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The day this record last observed a change in the document."
        },
        "effective_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "A date the publisher states for the document taking effect."
        },
        "source_url": {
          "type": "string",
          "description": "The address the document series is observed at."
        },
        "secondary_urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Further addresses the publisher serves the document at."
        },
        "topics": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Topic values recorded against the row."
        },
        "summary": {
          "type": "string",
          "description": "What the document is. Never what to do about it."
        },
        "watch_cadence": {
          "type": "string",
          "description": "How often this archive fetches the document."
        },
        "first_observed": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The day this row entered the observation series. Null before its first fetch, which is a real state on the day a row is admitted."
        },
        "observation_maturity": {
          "type": [
            "object",
            "null"
          ],
          "description": "How long this record has observed the DOCUMENT series for this row — the same referent the board renders its 90-day check bar from, and not counting witness reads of pages about the document. Carries days, the band that groups them (1-30, 30-90, 90-365, 1y+), and the first observed day. Counted from its own first observation to the record day, never from the day the archive began. Null where the row holds no document observation, which is not the same as a short one."
        },
        "corroboration_count": {
          "type": [
            "integer",
            "null"
          ],
          "description": "How many publisher surfaces independent of this record state the status. A count, never a grade, and never a confidence. Null where the status is unknown, because a row claiming nothing needs no corroboration."
        },
        "checked_by": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "human",
            "machine"
          ],
          "description": "The act that produced the status. `machine` is never a person confirmation and is never counted as one."
        },
        "check_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "The day the act named by checked_by was recorded."
        },
        "record_tier": {
          "type": "string",
          "enum": [
            "core",
            "register"
          ],
          "description": "`core` — this archive undertakes to close an entry’s open status question by rule on a clock, with its reason, and to re-read a ratification on record against its observation every night. `register` — observed and hashed daily, status machine-read where readable, and no person-verification is promised."
        },
        "robots_policy": {
          "type": [
            "string",
            "null"
          ],
          "description": "How the fetch of this row was permitted. Absent means the default case: robots read and allowed."
        },
        "field_verification": {
          "type": "object",
          "description": "Eight fields — identity, publisher, edition, status, effective_date, text, diff, notices — each an object carrying `state`, `basis`, `date` and `limit`. `state` is one of act · read · cited · held · read-not-there · withheld · not-measured, each defined in the envelope under `field_verification.states`. `basis` is one sentence naming the store, entry or count the state rests on. `date` is the day that basis was recorded, or null where none is. `limit` states a limit the basis carries, or null. The row-level `checked_by`, `check_date` and `last_verified` keep their own descriptions, each about the status field."
        },
        "verification_binding": {
          "type": "object",
          "description": "The act standing behind the row’s status, bound to one observation of the document. `state` is one of same-digest · differs · current-not-measured · no-standing-act · not-classified · no-observation-at-act, each defined in the envelope under `verification_binding.states`. `basis` is recorded-at-act (the act’s own log line records the observation) or nearest-observation-backfill (derived at build, the newest document observation with a digest at or before the act), or null where nothing is bound. `bound` and `current` each carry `observed_date` and `content_hash` (within a day, the digest names the observation), or null. `differs_since` is the day the current digest’s difference began, or null. `revision` is confirmed or not-confirmed where the digests differ, with `revision_ref` naming the entries or ledger lines, else null; confirmed only where every digest change since the bound observation is a confirmed revision by its before and after digest. `changes` carries `in_span` and `confirmed`, the digest changes from the bound observation to the current one and those a confirmed revision covers, or null where nothing differs. `sentence` states the binding in words, and says that the digest is of the document this row hashes as the record held it at the act, not what the act read."
        },
        "url": {
          "type": "string",
          "description": "The page this row is published at."
        }
      },
      "required": [
        "id",
        "title",
        "authority",
        "jurisdiction",
        "status",
        "source_url",
        "licence_class",
        "record_tier",
        "url",
        "text_retained",
        "quote_allowed",
        "snapshot_available",
        "rights_of"
      ],
      "additionalProperties": true
    }
  }
}