Motivation
A client cannot learn which citation systems a work uses without downloading that work's
whole alias index.
WorkSource lets an author declare additional_systems beside the preferred block
(scripts/source-schema.ts). The compiled Work record drops them: it carries
preferred_citation_system_key and nothing else (standard/schema/work.ts). So
/reg/works.json and /id/work/{key}.json both understate the work.
The only place that lists every system is /reg/work/{key}/aliases.json, as the keys of its
refs object. That file exists to map locators, not to describe a work, and it is large:
68 KB for the Republic, 745 KB for the Iliad, 1.18 MB for the Tanakh.
This was found while building /find/. To answer "is 514a a passage of this work?", the
finder must know the work's systems. Because the collection does not say, the check cannot
happen before the index fetch, and a client that only wants to describe a work has to
download every locator it has.
No work in data/ declares additional_systems today, so nothing is broken yet. The
roadmap plans growth into fields where a work under two systems is ordinary. ADR-0005
already treats it as a first-class case: the same locator string under two systems denotes
two different passages.
Proposed change
Project the work's citation systems onto the compiled Work record.
Two shapes are worth weighing:
citation_system_keys: string[], the full set, with preferred_citation_system_key
staying as the pointer into it. Additive, and the preferred key keeps its meaning.
additional_citation_system_keys: string[], only the fallbacks. Smaller, but a consumer
must union two fields to get the answer, which invites an off-by-one reading.
Option 1 is recommended. A consumer asking "which systems?" should read one field.
The compiler already has the data: it walks the preferred block and additional_systems to
build the references. The record is assembled from an explicit field list, so the field must
be added in scripts/compile.ts, in standard/schema/work.ts, in public/contexts/v1.jsonld,
and in the Work schema in api/openapi.yaml.
Alternatives considered
- Leave it. Clients read the alias index. Rejected. It makes describing a work cost a
megabyte, and it couples a description to a locator table.
- Add a
/reg/work/{key}/systems.json endpoint. Rejected. It is a third file for one
array that belongs on the record.
- Derive it client-side from
/reg/systems.json by testing every locator_regex.
Rejected. A regex match proves a locator's shape, never that the work uses that system.
Acceptance criteria
Notes
Depends on nothing, and blocks nothing. /find/ shipped in #93 and works around this by
splitting resolution into two stages: interpret() picks the work from the collections, and
resolveInIndex() decides the citation system only after fetching that work's alias index.
Closing this gap would let the finder reject an impossible locator before the large fetch,
and would let two user-facing strings stop hedging — the bare-locator candidate list is
built from preferred systems alone, so it says "main numbering" rather than claiming to
speak for the registry (src/pages/find/index.astro, case 'bare-locator').
Not urgent while no work declares additional_systems, which is true today.
Motivation
A client cannot learn which citation systems a work uses without downloading that work's
whole alias index.
WorkSourcelets an author declareadditional_systemsbeside the preferred block(
scripts/source-schema.ts). The compiledWorkrecord drops them: it carriespreferred_citation_system_keyand nothing else (standard/schema/work.ts). So/reg/works.jsonand/id/work/{key}.jsonboth understate the work.The only place that lists every system is
/reg/work/{key}/aliases.json, as the keys of itsrefsobject. That file exists to map locators, not to describe a work, and it is large:68 KB for the Republic, 745 KB for the Iliad, 1.18 MB for the Tanakh.
This was found while building
/find/. To answer "is514aa passage of this work?", thefinder must know the work's systems. Because the collection does not say, the check cannot
happen before the index fetch, and a client that only wants to describe a work has to
download every locator it has.
No work in
data/declaresadditional_systemstoday, so nothing is broken yet. Theroadmap plans growth into fields where a work under two systems is ordinary. ADR-0005
already treats it as a first-class case: the same locator string under two systems denotes
two different passages.
Proposed change
Project the work's citation systems onto the compiled
Workrecord.Two shapes are worth weighing:
citation_system_keys: string[], the full set, withpreferred_citation_system_keystaying as the pointer into it. Additive, and the preferred key keeps its meaning.
additional_citation_system_keys: string[], only the fallbacks. Smaller, but a consumermust union two fields to get the answer, which invites an off-by-one reading.
Option 1 is recommended. A consumer asking "which systems?" should read one field.
The compiler already has the data: it walks the preferred block and
additional_systemstobuild the references. The record is assembled from an explicit field list, so the field must
be added in
scripts/compile.ts, instandard/schema/work.ts, inpublic/contexts/v1.jsonld,and in the
Workschema inapi/openapi.yaml.Alternatives considered
megabyte, and it couples a description to a locator table.
/reg/work/{key}/systems.jsonendpoint. Rejected. It is a third file for onearray that belongs on the record.
/reg/systems.jsonby testing everylocator_regex.Rejected. A regex match proves a locator's shape, never that the work uses that system.
Acceptance criteria
Worknames every citation system the work declares./reg/works.json,/id/work/{key}.json, anddist/dump/works.jsonl.scripts/validate-data.tspasses.api/openapi.yamlmirrors the field.it.
additional_systemsand a work without.Notes
Depends on nothing, and blocks nothing.
/find/shipped in #93 and works around this bysplitting resolution into two stages:
interpret()picks the work from the collections, andresolveInIndex()decides the citation system only after fetching that work's alias index.Closing this gap would let the finder reject an impossible locator before the large fetch,
and would let two user-facing strings stop hedging — the bare-locator candidate list is
built from preferred systems alone, so it says "main numbering" rather than claiming to
speak for the registry (
src/pages/find/index.astro,case 'bare-locator').Not urgent while no work declares
additional_systems, which is true today.