# Prism — machine access contract

The stable contract for reading Prism programmatically. Served at
/machine-access.txt; mirrored in the repo at docs/machine-access.md.

## 1. Machine-readable headline value (no JavaScript required)

Every series page at /statistics/<slug> that has a single headline figure renders it
in an HTML <data> element with a stable id and data-* attributes:

  <data id="headline-value"
        data-measure="All-Items CPI, year-on-year"
        data-value="16.08"
        data-unit="%"
        data-period="2026-07">16.08%</data>

  - id="headline-value"  one per page, on the canonical latest value only.
  - data-measure         the labelled measure (a headline is never a bare number).
  - data-value           the raw numeric value, unformatted.
  - data-unit            the unit, when the series has one (may be absent).
  - data-period          the ISO period the value is for (2026-07, 2022, 2022-Q4).

Extract it from static HTML, e.g.:

  curl -s https://<host>/statistics/<slug> | grep -o 'id="headline-value"[^>]*'

A single-period distribution (a breakdown, not a time series) has no single headline
value, so it carries no #headline-value element. That is intentional, not a gap.

## 2. schema.org/Dataset (JSON-LD)

Every series page embeds a <script type="application/ld+json"> Dataset object:

  - @id / url            the canonical series URL.
  - name, description, temporalCoverage, variableMeasured (unit), spatialCoverage.
  - identifier           the series' prism-series-<slug> id (plus any merged-away
                         series' ids, so old citations still resolve).
  - isPartOf             the source publication (its name carries no doubled period).
  - publisher / creator  the publication publisher and the source-table originator.
  - distribution         two DataDownload entries — text/csv and application/json —
                         at /api/series/<slug>/csv and /json. Open, no auth.
  - includedInDataCatalog  Prism.

No license field is emitted. Prism grants no new rights over the underlying source
data, and reuse terms vary by source publisher (see /sources), so no single dataset
licence is asserted. A license will be added here only once one is genuinely settled.

## 3. Open downloads

  - /api/series/<slug>/csv    CSV.  No auth, no key, no query string required.
  - /api/series/<slug>/json   JSON. Same.

Each reconstructs the whole series: member/geography, period, value, unit, source.

## 4. Discovery

  - /sitemap.xml   every indexable URL.
  - /llms.txt      orientation for language models: entity map, URL grammar, citation.

## 5. Citation

  "<Series title>", <source publication / originator>. Catalogued by Prism, <series URL>.