Cite the Record
Menu

Shard schema

Record shard · 0.4.0

A single public record — written question, ministerial statement, oral evidence session, debate contribution, bill, division vote, committee report. Carries title, body text, source URL, breadcrumbs, named entities, system metadata, optional ParliamentTV block for broadcast records, and the full provenance chain back to the official source.

This page is the field reference for developers and AI clients. If you came here looking for a specific record, browse the search instead.

Draft field reference. Canonical .json file not published.

Verified example pending /schemas/record@0.4.0.json (pending) Authoritative source Use with AI

Required fields

10

Optional fields

7

Dialect

JSON Schema draft 2020-12

Version

0.4.0

Required fields

Every shard validating against record@0.4.0 ships these fields. Provenance lines show where each value comes from — the load-bearing column for the structured-evidence promise.

  • stableId string

    CTR-stable record identifier; survives source-side ID churn.

    Provenance: Generated at intake from recordType + publication date + source officialId.

    e.g. wq-2026-02-19-hcq-156802

  • officialId string

    Identifier in the authoritative source system.

    Provenance: Taken verbatim from the per-source identifier field (Hansard contributionId, Written Questions questionId, Members API memberId, Bills API billId).

    e.g. HCQ156802

  • recordType enum (7 values)

    Record-type bucket.

    • written_question
    • written_statement
    • oral_contribution
    • oral_evidence
    • division_vote
    • bill
    • committee_report

    Provenance: Determined at intake from the source endpoint that supplied the record.

  • title string

    Title or question text.

    Provenance: Verbatim from the source heading (WQ heading, statement title, Hansard contribution heading).

  • publishedAt string<ISO 8601>

    When the source published this record.

    Provenance: Source-provided publication timestamp; normalised to UTC.

  • sourceUrl string<URL>

    Canonical URL on the official source.

    Provenance: Constructed at intake from the per-source officialId via the documented URL template; checked for HTTP 200 at fetch time.

  • parserVersion string

    Parser name + version that emitted this record.

    Provenance: Pinned by the intake pipeline; each parser carries its own semver.

    e.g. written_question_detail@3.0.2

  • licenceAttribution string

    Required licence-attribution line for derivative use.

    Provenance: Static per source family — e.g. Open Parliament Licence v3.0 for Parliamentary material.

  • contentCompletenessStatus enum [content_complete | content_partial | content_unavailable]

    Did we capture the full content?

    Provenance: Set by the intake parser based on whether body extraction succeeded, was partial, or failed.

  • provenance object

    Cryptographic provenance for the bytes we fetched.

    Provenance: Emitted by intake fetcher at retrieval time.

    Nested fields (6)
    • sourceEvidenceId integer

      Internal evidence-store row identifier for ops debugging.

      Provenance: Intake evidence-store row id; useful for ops but not load-bearing for verification (the SHA-256 below is).

    • evidenceSha256 string<SHA-256>

      SHA-256 hash of the retained raw bytes.

      Provenance: Computed at fetch over the raw response body; load-bearing for the trust contract.

    • requestUrl string<URL>

      Exact URL the fetcher requested (often a sibling API endpoint).

      Provenance: Logged at fetch time; may differ from the canonical sourceUrl when intake uses an API alongside the HTML page.

    • fetchedAt string<ISO 8601>

      When the fetcher retrieved the bytes.

      Provenance: Fetcher wallclock at retrieval; UTC.

    • parserVersion string

      Parser version that produced this shard (echoed for chain-verification).

      Provenance: Same as the top-level parserVersion above; duplicated so a single shard line in a JSONL bundle is self-contained.

    • retainedBytesAvailable boolean

      Whether the archived envelope is still retrievable from the evidence store.

      Provenance: Set by the retention manager; false if the bytes were pruned under retention policy.

Optional fields

Present where the source carries the value or the derivation succeeds. Code consuming this schema should treat them as nullable.

  • house enum [Commons | Lords | Joint] · optional

    House the record belongs to.

    Provenance: Source endpoint or explicit house field on the source response.

  • session string · optional

    Parliamentary session.

    Provenance: Source field; conventional `YYYY-YY` form.

    e.g. 2025-26

  • bodyText string · optional

    Full body text of the record where licence permits.

    Provenance: Extracted from the source API JSON or the HTML body element; whitespace-normalised but never paraphrased.

  • excerpt string · optional

    Short excerpt for list views (≤300 chars).

    Provenance: Programmatically truncated from bodyText at a word boundary; never paraphrased.

  • parliamentTV object · optional

    Broadcast metadata for debate-derived records.

    Provenance: Joined at intake from ParliamentLive metadata where the source carries a broadcast reference.

    Nested fields (4)
    • eventId string

      ParliamentLive event identifier.

      Provenance: Parliament TV API event reference.

    • inSeconds integer

      Start offset of this contribution.

      Provenance: Hansard contribution → ParliamentLive timestamp join performed at intake.

    • outSeconds integer

      End offset of this contribution.

      Provenance: Same as inSeconds.

    • embedUrl string<URL> · optional

      Direct embed URL with in/out params.

      Provenance: Constructed at intake from the ParliamentLive URL template.

  • entities array<object> · optional

    Named entities linked to this record.

    Provenance: Per-record entity links produced at intake from speaker / addressee / mentioned-entity fields in the source feed; never inferred from body text by LLM.

  • systemMetadata array<object> · optional

    Metadata strip rendered on the record-detail page.

    Provenance: Composed from record fields at shard-build time.

Source families for planned record data

The following real source-family taxonomy is associated with record@0.4.0. Click through for metadata and publication status.

Related schemas

Entities referenced by this shard kind. A record shard's entities[] / nested references resolve to shards of these kinds.

Versioning + dialect
Schema id
record@0.4.0
Dialect
https://json-schema.org/draft/2020-12/schema
Canonical .json
/schemas/record@0.4.0.json (pending)
Verified example
Not linked until a verified live example is available.

Each planned schema follows semver. Patch bumps are additive and backwards-compatible. Minor bumps may add required fields or change validation rules. Major bumps will use a new URL path once canonical files are published.

Published structured data will declare its version in a $schema field. AI clients should respect that version when files become available.