TextRefs
Overview
HTTP contract for the canonical `/id/` namespace on textrefs.org.
TextRefs Registry & Resolver 0.1.0
Section titled “TextRefs Registry & Resolver 0.1.0”Every TextRefs record is served at two static URLs:
/id/{type}/{key}/— HTML for browsers./id/{type}/{key}.json— JSON-LD for machines.
There is no Accept-header content negotiation. Clients either
follow the <link rel="alternate" type="application/ld+json" href="…json">
advertised in the HTML head, or simply append .json to the canonical
URL. JSON bodies carry the JSON-LD @context at
/contexts/v1.jsonld; the
Zod schemas in
standard/schema/
remain the source of truth.
The Accept-Language / edition-based 303 redirect on
/id/ref/{uuid} to a resolver-target manifestation is planned but not
yet live.
A client that does not yet know a key starts at /reg/works.json or
/reg/systems.json. A client that knows a work key, a citation system
key, and a locator reads the reference UUID from
/reg/work/{key}/aliases.json. It needs no UUIDv5 implementation of its
own. /dump/ carries the whole registry as newline-delimited JSON, plus
the whole alias table as one JSON object, for bulk consumers.
The site is static, and the host derives every Content-Type from the
file extension. This contract therefore declares the media type that
the host actually sends, not the media type that best describes the
payload. A record or collection .json body is JSON-LD by content and
arrives as application/json. The two alias artifacts are plain JSON
and arrive the same way. A .jsonl body is newline-delimited JSON by
content and arrives as application/octet-stream. This contract is
published at
/api/openapi.yaml, byte for
byte as it is written, and arrives as text/yaml. A miss carries no JSON
at all: the host serves the site’s HTML 404 page. Parse by documented
shape, not by response header.