Large-record narrative and source-access contract

Large-corpus producers can give an individual record an authored Narrative view and can explicitly control how Explorer presents an external source. Both contracts are additive to okf-explorer-large-corpus.v1.

Record narrative

A hydrated record may publish narrative:

{
  "narrative": {
    "title": "Apply within the enclosing process",
    "body": "Repository-authored **Markdown** explaining context and boundaries.",
    "process": { "route": "process/example", "label": "Example process" },
    "previous": [{ "route": "episode/before", "label": "Before" }],
    "next": [{ "route": "episode/after", "label": "After" }],
    "variants": [{ "route": "variant/scotland", "label": "Scotland" }],
    "related": [{ "route": "dataset/related", "label": "Related route" }]
  }
}

body is required when narrative is present. Explorer passes it through its safe Markdown renderer. Route links are optional and use the same governed routes as graph, search and record-locator indexes. When a selected record has this contract, Narrative shows it before any corpus-level reduction summary.

Typed source access

A resource may publish one source_access object:

{
  "source_access": {
    "url": "https://publisher.example/service.xml",
    "label": "Official service response",
    "media_type": "application/xml",
    "display_mode": "xml"
  }
}

All four fields are required. display_mode is one of:

• link: Explorer does not fetch the response and offers Open official source;
• json: Explorer requests JSON, parses it and offers summary, tree and raw views;
• xml: Explorer requests XML and displays the response as inert text; or
• text: Explorer requests text and displays the response as inert text.

Explorer never executes source markup and applies a 10 MB display limit. A failed browser fetch leaves the official source link available. Source responses are held only in page memory: Explorer does not snapshot, persist or redistribute them.

The record-level source_api_url field remains supported as legacy JSON-only behaviour. It cannot opt an XML, text or HTML response into the inline viewer; producers must publish a typed resource instead.

This contract describes presentation, not authority. Producers remain responsible for source identity, assertion provenance, jurisdiction, rights, freshness and limitations.

Further format-specific work

The current contract gives one resource one bounded display mode. Future work tracked under issue #76 should retain, rather than replace, that safe baseline:

• allow a record to describe several representations of the same source with stable resource IDs, roles, media types and optional format profiles;
• select a renderer from the declared media type and profile, then validate the returned Content-Type, using a file extension only as a conservative compatibility fallback;
• distinguish an unavailable representation (406), missing resource (404), browser cross-origin restriction, invalid declared-format response and size limit in user-facing errors; and
• add regressions proving that CLML/XML is never sent through JSON parsing, point-in-time URLs keep their date, malformed XML fails safely, source markup remains inert and legacy JSON inspection still behaves as documented.

A specialist legislation view may reuse a typed XML representation, but its provision tree, legal status and point-in-time interpretation remain a separate domain contract rather than a generic consequence of display_mode: xml.