Repository navigation
docs: add more systems like IIIF #81
Description
Activity
Done, on
stagingin #80Landed as
159703a, squash-merged intostagingwith the rest of the documentation wave (3f6670e). All six suggestions are in. The page is now Related standards and systems — the title and the framing changed, the URL did not, so no redirect is needed.The six suggestions
- Broader framing. The opening now says the systems work at different layers of textual reference, that very few of them compete with TextRefs, and that some supply mapping targets while others describe the encoded edition, the digitized object, the annotation, or the bibliographic record.
- IIIF Presentation API — new Digital surrogates section, with your distinction kept as prose under the table: TextRefs answers which canonical passage is this?, IIIF answers where does that passage appear in this digitized edition? The row states that a IIIF resource showing one passage belongs in
resolver_targets, not in aMappingAssertion. - W3C Web Annotation — sits with TEI under Edition and fragment addressing, with the short comparison you asked for: a TextRefs URI is the canonical semantic reference and holds whatever edition or rendering you open; a selector is a representation-specific location and holds for the one text it was anchored to. The section closes by noting IIIF builds on this model, which is what carries the reader into the next section.
- RAMEN — its own Editorial conceptual models section, described from its own documentation (Collection, Content, Annotation, Entity; explicitly not a replacement for TEI or IIIF), followed by the division of responsibilities from this issue: RAMEN editorial objects, TEI encoding, IIIF presentation, TextRefs canonical references. Flagged in the page as a recent model, so a reader can weigh its standing next to TEI and IIIF.
- BIBFRAME and IFLA LRM — added to Bibliographic and authority models. The section is explicit that Wikidata and VIAF supply mapping targets today, while BIBFRAME and IFLA LRM show where TextRefs sits relative to library metadata. BIBFRAME's Instance level is named as what a DOI or an ARK identifies; LRM's work-to-manifestation split is named as the same split TextRefs makes.
- URN:NBN — added, and it was the pure consistency gap you suspected: Appendix B of the specification (
specification.md:450) and the mappings guide both already listed it, and only this page did not. The section now links to Appendix B so the two lists are visibly the same list.
Organisation
Your seven groups, adopted as written, each with one framing sentence and the same four columns the old table had:
Section Systems Canonical reference and text APIs CTS URN, DTS Persistent object and publication identifiers DOI, Handle, ARK, PURL, URN:NBN Bibliographic and authority models Wikidata, VIAF, BIBFRAME, IFLA LRM Edition and fragment addressing TEI xml:id, W3C Web AnnotationDigital surrogates IIIF Presentation API Editorial conceptual models RAMEN Platforms and resolvers Perseus / Scaife The two closing sections, Where DOIs fit and What this means for implementers, are unchanged apart from one new implementer bullet: target the TextRefs IRI when you mean the canonical passage, and keep selectors, canvases and TEI anchors for the representation you actually annotated.
The inbound links in
get-started/index.mdandhow-it-works.mddescribed the page by listing ten systems, which is how it drifted in the first place. They now describe it by its layers.Deliberately not in this change
Nothing was added to Appendix B of the specification, and the contributor rules in
mappings-and-resolver-targets.mdare untouched. Both new rows follow the ADR-0006 test that already governs TEI anchors — a resource that only lets a reader inspect one passage is aresolver_targetsentry. Making a IIIF Manifest a legitimateMappingAssertion.targetis a different question: it turns on whether a Manifest for a digitized edition denotes a textual resource under §10, which is a modelling decision and wants its own ADR rather than a docs edit. Worth filing if you want it for v0.2.0.Verification
npm run verify:fastgreen (30/30 tests, all internal links valid). Every external link added returns 200 — IFLA LRM points atrepository.ifla.org/handle/20.500.14598/40, the 2018 model document, because theifla.organdiflastandards.infoalternatives either 403 or do not carry the entity definitions. The Appendix B anchor the URN:NBN section targets is confirmed present in the built HTML.Labelled
addressed-in-v0.1.0rather than closed, per the release convention in #68 — it ships when #4 merges and the tag lands.- added a commit that references this issue
on Aug 27, 2026
Affected page or file
https://textrefs.org/get-started/related-systems/
What's missing, wrong, or unclear?
The "Related systems" (https://textrefs.org/get-started/related-systems/) page would benefit from a broader framing and clearer organization.
At the moment, the page is presented mainly in terms of “identifier systems,” but the systems already listed operate at several different layers: persistent identifiers, authority data, APIs, local text anchoring, and reading platforms. This makes it difficult to understand how each system relates to TextRefs.
Suggested changes
Consider renaming or reframing the section from “Related identifier systems” to something like “Related standards and systems.”
The important distinction is not simply whether a technology provides identifiers, but which layer of textual reference and interoperability it addresses.
IIIF is one of the most important missing systems.
It provides identifiers and structures for particular digitized objects and their parts—such as Manifests, Canvases, and Ranges—while TextRefs can provide an edition-independent identity for a canonical passage.
This would help explain a useful distinction:
Web Annotation is another important complement to TextRefs.
Its selectors can anchor an annotation to a particular representation or fragment of text, whereas a TextRefs URI can provide a stable canonical target independent of that representation.
A short comparison would clarify:
This is especially relevant because IIIF itself builds on the Web Annotation model.
"RAMEN" (https://ramen-schema.org/concepts) is useful as a higher-level editorial model.
RAMEN models concepts such as Collection, Content, Annotation, and Entity without replacing standards such as TEI or IIIF. TextRefs could fit naturally into this ecosystem as the canonical-reference layer—for example, as the target identified by an annotation.
This provides a useful division of responsibilities:
The page could also mention a bibliographic model such as BIBFRAME or IFLA LRM.
Their distinctions between abstract works and particular realizations or instances are relevant to TextRefs' own distinction between a canonical work/passage and the editions or manifestations in which it appears.
They do not compete with TextRefs, but help readers understand where TextRefs sits relative to library metadata.
URN:NBN should be included if it is already recognized elsewhere in the TextRefs specification alongside schemes such as DOI, ARK, Handle, and PURL.
This appears to be a straightforward documentation consistency issue.
Possible organization
Rather than one flat list, the page could group systems by function:
The main documentation goal would be to make clear that these systems are generally complementary layers rather than alternatives to TextRefs.
Suggested wording or fix
No response