TextRefs
v0.1.0 status: everything is a draft (on purpose) — release staged, review invited #31
Replies: 2 comments
|
Status update — what changed since 6 July. The post above has been rewritten to describe the release as it now stands. Summary of the delta, for anyone who read the original: The release roughly doubled. ~39,200 references across 12 works → 86,397 across 23 works and 13 citation systems. The resolver review completed the New Testament and the Tanakh (both were a single book before), and a second wave added Dante's Divina Commedia, Hume's Treatise and first Enquiry, and eight Nietzsche works. Four more ADRs, so seven in total. ADR-0004 collapses the lifecycle to There is a public surface to try now, which there was not in July: One normative correction. The association exists. TextRefs was founded in Zürich on 2 September 2026. The Cantonal Tax Office of Zürich assured tax exemption on grounds of public benefit on 27 August 2026, on condition that we founded as presented — which we did. That assurance is not yet a legally binding decision, so donations are not tax-deductible yet. Full announcement: TextRefs is now an association. The release PR is content-complete. textrefs.org#4 carries the full detail on every point above, and review is still open until it merges. |
|
The release is content-complete. Two things landed since the last update, both found while reviewing the published ontology and both frozen by the tag if they had waited:
The second one is the kind of thing that is easy to miss in a data model review and obvious the moment you look at a rendered page. If you have five minutes, open a reference page and check what it claims about rights — for example the Nestle-Aland or Sefaria rows on any Tanakh or New Testament passage. Review is open until textrefs.org#4 merges. After the tag, changing any of this costs a documented migration. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
TextRefs v0.1.0 — the first tagged release of the standard, the site, and the seed registry — is staged and open for review before it ships. The release PR is textrefs.org#4 (staging → main), and it doubles as the community-review venue for the architecture decisions it adopts. Everything below is what that PR ships.
The headline decision: every record in the registry is
status: draft. TextRefs is not stable yet, and we've made that a feature of the data model rather than a disclaimer.What it ships
86,397 references across 23 works and 13 citation systems — 86,477 records in total, plus 172,838 aliases, all at
status: draft.The resolver review completed the New Testament (John only → 27 books) and the Tanakh (Genesis only → 39 books), so the baseline covers two complete biblical corpora rather than one book of each. A second wave then added Dante's Divina Commedia (14,233 lines, the canonical count), Hume's Treatise and first Enquiry, and eight Nietzsche works.
The seven ADRs (
decisions/)dcterms:conformsToreplacestarget_kind(fromtarget_kind: prefer a dereferenceable IRI +dct:conformsToover an enumerated scheme list #6): mapping targets no longer carry a curated scheme label backed by an ever-growing appendix table; an optionalconforms_toIRI carries the conformance claim instead, following Linked Art practice. TheidentifierIRI stays authoritative.(work_key, citation_system_key, locator)alone —normalization_versionis gone from the data model. Anyone holding the canonical fields can compute the registry UUID offline; the registry stays authoritative for which locators are canonical.draft→active. Promotion grants recommendation and identifier permanence in a single expert-review gate, because nothing ever treatedcandidatedifferently fromactiveexcept the recommendation.Worknames one, and it mints the bare/cite/{work}/{locator}alias. Fallback systems get qualified/cite/{work}/{system}/{locator}aliases.prov:alternateOf(another entity denoting the same work) anddcterms:isReferencedBy(a document about the work), chosen by the nature of the target rather than by confidence.closeMatchis removed outright.alternative_labels(feat(standard): name works by abbreviation and translated title (#85) #89): aWorkMAY carry a flat list of the other names a scholar searches by — abbreviations (NE,LXX,PI), Latin or Greek titles, translated titles — published asskos:altLabel. Identity-neutral: no label is a UUID seed input, so a label change never moves an identifier. Two works MAY claim the same label (Ethicsfits Aristotle and Spinoza).ADR-0005 and ADR-0006 both re-mint IRIs. Landing them before the first tag costs nothing, because every record is
draftand no identifier has ever been published. After the tag the same change would cost a documented migration against a baseline people may already cite.What you can actually call
Since July the release has grown a public surface that did not exist when this post was written:
/find/— type the citation you already write (Plato Republic 514a,NE 1094a1) and get a permanent link, the editions that carry the passage, and a citation to paste. It is a static page that reads the same public endpoints any other client reads. Nothing is guessed: a near miss asks "did you mean …?" and never resolves on its own./reg/works.jsonand/reg/systems.json— collection endpoints, so a client no longer has to know a key before it can fetch anything./reg/work/{key}/aliases.json— a per-work locator index. A client that knows work, system and locator resolves a passage in two fetches, parsing JSON alone, without re-implementing the ADR-0002 UUID seed./dump/— the bulk artifacts and theirdatapackage.jsondescriptor, with a byte count and asha256for each./schemas/v1/textrefs.schema.json— the normative JSON Schema the specification names, generated from the canonical Zod schemas on every build. All 86,477 records validate against it./api/openapi.yaml— the contract itself, byte-identical to the file the docs render./ontology/and/ontology.json— the 17tr:terms the v1 context has always used and nothing ever defined. Established terms are reused where they fit:keyisdcterms:identifier,locatorisskos:notation.Standard changes
@context(Add a complete worked example including@context#8) — both from community review.superseded_by(dcterms:isReplacedBy);MappingAssertionstays reserved for work-level equivalence with a Work-IRI subject (standard: MappingAssertion.subject Work-IRI constraint conflicts with tombstone/versioning successor links #10).Workrecords carry direct relation edges, so RDF-aware clients can follow mappings without dereferencing the reified assertions (standard: JSON-LD output does not emit direct SKOS mapping triples #11).dcterms:licensehas a single IRI-typed range: authored SPDX ids are emitted as canonical SPDX IRIs (standard: license and license_url both map to dcterms:license (mixed literal/IRI range) #12). Correction (license and license_url both expand to dcterms:license, giving a target two licence IRIs #129):license_urlpublishes asdcterms:rights, notdcterms:license— every value in the registry is a rights statement about the target (a terms page, an imprint), not a licence text, and the old mapping put two unranked IRIs on one predicate for 50,047 targets. Reference pages now show both: the licence as its SPDX identifier, and the rights statement as aRightslink (Resolver-target licence tag shows a full URL instead of an SPDX identifier #133, Reference pages never render license_url, hiding rights for 54,380 targets #144). Before that, 54,380 targets — every Deutsche Bibelgesellschaft and Sefaria edition — displayed anopenchip and nothing else, which read as "freely usable" when the registry had recorded the opposite.application/ld+jsonfor the JSON-LD siblings, UUID-namespace clarifications, tombstone/alias prose fixes (standard: erratum — editorial batch (RFC 9562, ld+json media type, aliases.json, tombstone rationale, namespace note) #14).Registry data (textrefs/registry)
draft— a one-time bootstrap demotion; the promotion ladder is one-way from here.description;examplesandnormalization_versionare gone.1Cor), no leading zeros anywhere they aren't attested.Site and infrastructure
/cite/redirects and untranslated German fallback pages.The association exists now
TextRefs was founded as an association (Verein) in Zürich on 2 September 2026, under Art. 60 ff. of the Swiss Civil Code. The statutes were adopted at the founding assembly and took effect immediately.
On 27 August 2026 the Cantonal Tax Office of Zürich assured the association of tax exemption on grounds of public benefit, on condition that it was founded as presented. It was, and the signed statutes and founding minutes were submitted the same day. An assurance is not yet a legally binding decision, so donations are not tax-deductible yet — they become deductible once the decision arrives, and we will say so when it does.
One thing changed along the way: the tax office found Art. 15 broader than the governance model in our application, so board members now serve in an honorary capacity and may claim only their actual expenses and cash outlays. Nothing else.
The founding documents are public — statutes, mission, governance and expenses, with the German originals binding. Full announcement: TextRefs is now an association.
TextRefs stays bootstrap-funded, non-commercial, and committed to POSI. What is new is that there is now an entity that can hold funds, sign agreements, and outlive its founders — which is the point of making promises about permanent identifiers.
What this means for you
This is exactly the moment to propose works. New data merges as
draftafter technical review — no long-term commitment on either side, identifiers can still be fixed if wrong, and a re-proposed record regains the same UUID by construction. Expert review then promotes records toactive, which is when the persistence promise kicks in.The contribution funnel:
draft, appears on the site flagged as draft.active; the identifier becomes permanent.Where we want help
help wanted): islocator_regexthe right machine-checkable contract, or do some citation traditions need more? Design input from people who know their citation systems is wanted./find/and tell us where it fails. It is the one place where a scholar's own habits meet our data model, and it is the fastest way to show us a citation tradition we have modelled badly.Thanks to Julien A. Raemy for the pre-release review that prompted ADR-0001 and shaped the §13 worked example and the dereferenceability guidance.
Where the release actually is
Content-complete as of 3 September 2026. Every item above is merged to
stagingand green: the full CI gate reports 0 type errors, 137/137 tests, 259,813 pages built, and every internal link valid.What remains is mechanical — one deployment dispatch, one maintainer approval, then the tag. So this is the last window in which review can still change what ships. If you have been meaning to read the ADRs or the specification, now is the moment.
Release notes and the
v0.1.0tag follow once the PR merges.All reactions