Repository navigation
feat(spec)!: seed CanonicalReference UUIDs from the semantic identity tuple (ADR-0002) - #21
Merged
Conversation
… tuple Adopt ADR-0002 (fixes textrefs#15): reference UUIDs are computable offline from (work_key, citation_system_key, locator); normalization_version is removed from the data model entirely. Citation-system profiles now define canonical locator forms — non-canonical spellings are rejected at validation time, never folded — and a profile change that alters an accepted locator is a compatibility event (migration, breaking release, or new citation_system_key), not a version bump. - Zod schemas: drop normalization_version (reference + system), drop examples, add required CitationSystem.description; drop unused SemVer - compile/validate: 3-field LF-joined seed on both sides; systems emit description instead of normalization_version/examples - JSON-LD context + OpenAPI: same shape change (description = dcterms:description) - spec docs: identifier-syntax gains a purpose-of-determinism section and the canonicalization-change compatibility rule; system-profiles gains the canonical-locator-form section (relates to textrefs#13) - doc example UUIDs recomputed for the 3-field seed - data submodule → textrefs/registry#5 (systems gain description, lose normalization_version/examples) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Implements ADR-0002 by changing CanonicalReference UUID v5 seeding to be computable offline from the semantic identity tuple (work_key, citation_system_key, locator), and removes normalization_version from the model. Updates the spec, compiler/validator, JSON-LD context, and site pages to reflect the leaner CitationSystem contract (new required description, removal of examples).
Changes:
- Switch deterministic reference UUID seed from 4 fields to 3 fields (drop
normalization_version) in compile + validation. - Update
CitationSystemshape: requiredescription, removeexamples, and adjust schemas/pages/docs accordingly. - Refresh normative docs + JSON-LD context + OpenAPI to match the new field set and recomputed example UUIDs.
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| standard/schema/common.ts | Removes SemVer schema now that normalization_version is gone. |
| standard/schema/citation-system.ts | Drops normalization_version/examples, adds required description, simplifies validation to regex syntax check. |
| standard/schema/canonical-reference.ts | Removes normalization_version from CanonicalReference schema. |
| src/pages/id/system/[key]/index.astro | Updates system page to display description and removes examples/version UI. |
| src/pages/id/ref/[uuid]/index.astro | Removes normalization_version display from reference page. |
| src/lib/registry.fixture.ts | Updates fixture registry records to match new system/reference shapes. |
| src/content/docs/standard/system-profiles.md | Updates profile requirements and adds canonical-locator-form guidance aligned with ADR-0002. |
| src/content/docs/standard/specification.md | Updates normative model/requirements/examples for new seed and field set. |
| src/content/docs/standard/json-ld.md | Updates documented context mapping (adds description, removes normalization_version/examples terms). |
| src/content/docs/standard/identifier-syntax.md | Documents new 3-field seed sequence and adds “Purpose of determinism” section referencing ADR-0002. |
| src/content/docs/get-started/url-layout.md | Updates example canonical reference UUIDs/URLs. |
| src/content/docs/get-started/mappings-and-resolver-targets.md | Updates example CanonicalReference JSON to remove normalization_version. |
| src/content/docs/get-started/how-it-works.md | Updates identity tuple description and example UUID links/records. |
| src/content/docs/get-started/authoring.md | Updates authoring example system YAML to use description and removes examples/version fields. |
| scripts/validate-data.ts | Updates deterministic UUID check to use the new 3-field seed; keeps JSON-LD context completeness check. |
| scripts/compile.ts | Removes NORMALIZATION_VERSION, updates system/reference compilation and UUID seeding to 3 fields. |
| public/contexts/v1.jsonld | Adds description term and removes normalization_version/examples terms from the published context. |
| decisions/ADR-0002-uuid-seed-semantic-identity.md | Adds ADR documenting the rationale and trade-offs for the new seed + model simplifications. |
| api/openapi.yaml | Updates API schemas: remove SemVer and normalization_version/examples, add required description. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+156
to
+164
| Required: `id`, `key`, `type` (`CitationSystem`), `preferred_label`, `description`, `locator_regex`, plus administrative metadata. The `id` MUST be a persistent TextRefs HTTP URI of the form `https://textrefs.org/id/system/{key}`, where `{key}` is one flat key and occupies exactly one URI path segment. | ||
|
|
||
| - `description` documents the citation tradition and its canonical locator form in prose, including any canonical-form rules that cannot be expressed in `locator_regex`. | ||
| - `locator_regex` MUST be a valid ECMAScript regular expression. | ||
| - `locator_regex` provides machine-checkable pre-validation for locator shape only; it need not fully describe citation systems whose valid references cannot be expressed completely as a regular language. | ||
| - Citation systems SHOULD use an anchored `locator_regex` when the pattern is intended to describe the full locator string. | ||
| - Regex success does not by itself prove that a reference point exists in a work. | ||
| - `normalization_version` MUST use semantic versioning. | ||
| - `examples.valid` MUST all match `locator_regex`; `examples.invalid` MUST all fail it. | ||
| - Unicode handling for keys and locators MUST follow [Identifier syntax](/standard/identifier-syntax/#unicode-normalization). | ||
| - A pull request that adds or changes a citation system MUST include the profile, valid examples, and invalid examples. See [Citation-system profiles](/standard/system-profiles/). | ||
| - A pull request that adds or changes a citation system MUST include the full profile record. See [Citation-system profiles](/standard/system-profiles/). |
…xamples removal The CitationSystem contract no longer carries examples.valid/invalid; conformance now requires description + a valid ECMAScript locator_regex. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
modified bumped on all systems for the shape change; bible description aligned with its locator_regex (Copilot review on registry#5). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #15. Relates to #13.
What
Adopts ADR-0002 (included in this PR):
CanonicalReferenceUUIDs are seeded from the semantic identity tuple —work_key,citation_system_key, canonicallocator— LF-joined, namespace unchanged. Anyone holding the canonical fields can now compute the registry UUID offline; the registry remains authoritative for which locators are canonical and attested.normalization_versionis removed from the data model entirely (reference and system). Outside the seed it would version nothing that matters: locator-affecting profile changes are compatibility events regardless of a version label, and other rule evolution is visible viamodified. Keeping it as metadata would reproduce the confusion that motivated #15.Accompanying rules (spec-normative, per the ADR):
citation_system_key— never silent.locator_regexis the machine-checkable floor beneath it. Tightening the shipped regexes (Bekker leading zeros, Bible case) stays with standard: require canonical ASCII digit and case forms in citation-system profiles #13.Rides along, keeping
CitationSystemhonest:examplesblock removed — the compiler already testslocator_regexagainst every enumerated locator (~39k), a strictly larger test set.descriptionfield (dcterms:description), promoting the former YAML comments to a published field.Changes
compile.ts+validate-data.ts(3-field seed on both sides), fixture, record pages, JSON-LD context, OpenAPI.514a→dc799d4b-…,John.3.16→b6438d55-…).Verification
npm run build:data: 39,250/39,250 records valid, incl. the 3-field determinism check and JSON-LD context completeness.npm run verify: format + astro check + full build (78,940 pages), all internal links valid.normalization_versionsurvives only in ADR-0002.Since nothing is published yet, all reference UUIDs simply recompute — no tombstones (see ADR-0002 context).
🤖 Generated with Claude Code