Corpus documentation

Files and entry points

/data/index.json

Current term slugs, count and schemaVersion (1). Start here; do not invent slugs from display names.

/data/terms/<slug>.json

A single term. Its human-readable page is /terms/<slug>/.

/data/timeline.json

Historical events and their references.

/datasets/

Dataset landing pages link to CSV files, metadata, methods and any separately available calculation code.

/llms.txt and /llms-full.txt

Agent-oriented navigation and a combined textual view. These are not API credentials or a separate license grant.

Term schema, version 1

slug, term, aliases

Stable record identifier, canonical display name and alternative names. Use slug for joins, not the display text.

definition, note, status

Definition, explanatory context and one of shipping, limited, eol, cancelled, research or unknown. Technology status is not a confidence score.

advantages, limitations

Arrays whose entries may be strings or objects with text and citationIds. Support both representations.

related, supersedes, supersededBy

Arrays of term slugs. A relationship is not a product recommendation.

firstSeen, lastSeen

A historical date object with date and citationIds, or null. These are not publication dates.

citations

Source records with id, title, url and accessed. Citation IDs are local to their term; an access date is not the source's publication date.

provenance (optional)

An array of short source and scope caveats. Citation markers refer to the same record-local citations as the note. The HTML page presents these under Sources & caveats.

updated (optional)

A YYYY-MM-DD substantive editorial update date when recorded. Absence does not mean the record has never changed.

Consumers should tolerate additional fields, preserve unknown values and distinguish missing data from zero or an empty measurement. Resolve citationIds within the record and relation slugs against the index.

Minimal examples

Python 3, standard library

import json
from urllib.request import urlopen

base = "https://hesela.dev"
with urlopen(base + "/data/index.json", timeout=20) as response:
    index = json.load(response)
if index["schemaVersion"] != 1:
    raise ValueError("Review the schema before importing this version")
if "cmr" not in index["slugs"]:
    raise ValueError("Requested term is not in this snapshot")
with urlopen(base + "/data/terms/cmr.json", timeout=20) as response:
    term = json.load(response)
print(term["term"], term["definition"])

JavaScript, Node.js 22 or later

const base = "https://hesela.dev";
async function readJson(path) {
  const response = await fetch(base + path, {
    signal: AbortSignal.timeout(20000)
  });
  if (!response.ok) throw new Error("HTTP " + response.status);
  return response.json();
}
const index = await readJson("/data/index.json");
if (index.schemaVersion !== 1) throw new Error("Unsupported schema");
const term = await readJson("/data/terms/cmr.json");
console.log(term.term, term.definition);

Examples fetch the current public files. Network failures, rate limits and malformed responses must be handled by the consuming application. Cache completed downloads and avoid fetching the whole corpus on every page view.

Versions and reproducibility

schemaVersion identifies the record format, not an immutable release of every definition. The current URLs can change. A generatedAt timestamp records a data-generation event, not an editorial review.

For reproducible work, retain the files you used where their licenses permit it, together with their URLs, access time, schemaVersion and cryptographic hashes. Do not assume an earlier snapshot remains available at the live URL. Follow recorded term updates or RSS.

Dataset checks

Read the landing page and JSON metadata before interpreting a CSV. Check column meanings, units, population, time window, missing-value conventions, method, limitations and rights. A table of extracted paper results is not the paper's raw observations. Synthetic records are not measurements.

Some artifacts include generators, tests, input assumptions and hashes. Reproducing deterministic arithmetic does not independently validate a study or model. Do not automatically execute downloaded code; inspect its dependencies and resource requirements first.

Rights and corrections

Follow each artifact's explicit license; no blanket permission is implied by this endpoint documentation. See citation and reuse guidance. Send data or documentation corrections to support@hesela.com.