Skip to content

feat: name every citation system a work uses in the Work record #91

Description

@maehr

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:

  1. 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.
  2. 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

  1. 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.
  2. Add a /reg/work/{key}/systems.json endpoint. Rejected. It is a third file for one
    array that belongs on the record.
  3. 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

  • The compiled Work names every citation system the work declares.
  • The preferred system stays identifiable.
  • The field appears in /reg/works.json, /id/work/{key}.json, and
    dist/dump/works.jsonl.
  • The JSON-LD context declares the term, so scripts/validate-data.ts passes.
  • api/openapi.yaml mirrors the field.
  • No identifier moves. ADR-0002 fixes the reference UUID seed, and this field is not in
    it.
  • A test covers a work with additional_systems and a work without.

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpost-v0.1.0Deferred past the v0.1.0 baseline. Revisit if the need arises.standardThe published specification and schemas

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions