Repository navigation
Description
Context
public/contexts/v1.jsonld binds the tr: prefix to https://textrefs.org/ontology# and then uses it for 20 terms: four classes (tr:Work, tr:CitationSystem, tr:CanonicalReference, tr:MappingAssertion) and sixteen properties (tr:key, tr:locator, tr:relation, tr:status, tr:workKey, tr:citationSystemKey, tr:preferredCitationSystemKey, tr:creatorKind, tr:subject, tr:target, tr:identifier, tr:resolverTargets, tr:access, tr:lastChecked, tr:locatorRegex).
None of them dereferences. https://textrefs.org/ontology# returns nothing. Every published record therefore carries twenty terms that a Linked Data client cannot resolve to a definition.
ADR-0006 named this and declined to fix it there:
Publish an ontology stub at
https://textrefs.org/ontology#. Pre-existing debt (tr:Work,tr:relation,tr:locatorare all undereferenceable), not created here, but option 4 above was rejected partly on its account.
That last clause matters. ADR-0006 chose prov:alternateOf and dcterms:isReferencedBy over minting tr: terms partly because a tr: term would have been one more undereferenceable IRI. The debt is now shaping decisions, not just sitting behind them.
What the stub needs
- A document served at
https://textrefs.org/ontology, with the fragment identifiers the context uses. - One definition per term: a label, a comment, and — where it is honest to state one — a domain and a range. A stub may leave a term loosely specified. It may not leave it undefined.
- Content negotiation is not available. The site is static and GitHub Pages derives every
Content-Typefrom the file extension, asapi/openapi.yamlalready documents. Publish HTML with embedded RDFa or JSON-LD, or publish a Turtle file at a distinct path and link it, rather than promising negotiation the host cannot perform. - Versioning. The context is
v1. The ontology needs a stated relationship to it — whether the terms are versioned with the context or independently.
Decide first
- Reuse where a term already exists. Several
tr:properties may be expressible with SKOS, DCTerms or schema.org terms that do dereference. A stub is the moment to check, because replacing a term after v0.1.0 is a context change with published consumers. - Scope. All 20 terms, or the four classes first?
Links
decisions/ADR-0006-mapping-relation-vocabulary.md— the follow-up and the rejected option 4public/contexts/v1.jsonld— the 20 termssrc/content/docs/standard/json-ld.md— the published context documentation
Activity
docs(decisions): refresh the ADR follow-up checklists before the v0.1…
refactor(standard): keep the ontology work inside JSON-LD 1.0 and ADR…
feat(standard): publish the TextRefs ontology (#127)
maehr commentedon Sep 2, 2026
Fixed on
stagingby2d71119(#127). All 17tr:terms are defined insrc/lib/ontology.tsand served at/ontology/(HTML) and/ontology.json(JSON-LD). Three of the terms this issue counted are gone rather than defined:keyis nowdcterms:identifierandlocatorisskos:notation, reusing an established term where one fits, as the issue asked.The fix ships with the
v0.1.0release, #4. Closing now rather than at the tag, because the change is onstagingandClosesdoes not fire from a merge into a non-default branch.