resolve-authorities

This skill runs stage 5 of the pipeline. It reads the needs_verification candidates the generation stage proposed, looks each one up against the authority file its vocabulary points to, and writes the result back onto the record: a confirmed URI where the match is exact, the alternatives surfaced where the match is close, and a manual-entry flag where there is none. It is deterministic. There is no language model in this stage. The model proposed the candidate at stage 4; here an authoritative lookup disposes of it, and the human confirms at stage 6.

For the design rationale, the full authority-source landscape, and why moving identifier assignment out of the model is the central trust mechanism, see ../../docs/authorities.md. This file is the operator procedure that document points to.

Where it runs

Stage 5, after generation (stage 4) and before human review (stage 6). In the improvement loop it runs every round between generation and review, so the cataloguer adjudicates records whose authority work is already done rather than raw model strings. See the stage table in ../../docs/architecture.md and the loop in ../../docs/the-improvement-loop.md.

Inputs and outputs

Reads and writes records conforming to ../../schemas/metadata-record.schema.json.

• Input: every fieldValue in a record's fields whose authority_status is needs_verification. Each carries an authority_candidate (the label the LLM proposed) and a vocabulary (which names the authority to query). Values marked n/a are not controlled and are skipped; values already verified are skipped.
• Routing: route each candidate by its vocabulary, and for depicted_entities also by its entity_type. The vocabulary priority order is the institution's, read at run time from the application profile (controlled_vocabularies in ../../schemas/application-profile.schema.json). The authorities and what each resolves are tabulated in ../../docs/authorities.md: id.loc.gov (LCSH, LCNAF, LCGFT), Getty (AAT, TGN, ULAN), FAST, VIAF, Homosaurus, with Wikidata as a cross-reference when an entity is not in the library or Getty files.
• Output: the fieldValue is transitioned in place. On an exact match, authority_uri is filled with the matched record's URI and authority_status becomes verified. On a near match or no match, both stay as they were (authority_uri null, authority_status needs_verification) and the value goes to the review queue. Near matches and missing-authority notes are added to the record's review_flags so the cataloguer sees them at stage 6.

Each verdict attaches to the value's stable value_id (for example subjects.01), which holds across re-runs, so a result lands on the same value even when an array reorders between rounds. Operate and report by value_id throughout.

The endpoint specifics

The query path, parameters, and response shape for each service are an implementation detail and are deliberately not fixed in prose, because each authority (the id.loc.gov label-suggestion service, the FAST lookup interface, the Getty SPARQL endpoint, VIAF autosuggest, the Homosaurus and Wikidata linked-data interfaces) has its own contract. Before relying on any of them, [verify] the current request path and parameters against the service's published documentation; do not reconstruct an endpoint from memory or invent one. Wire each service as a small, named, testable lookup function so the stage stays deterministic and auditable.

The three dispositions

For each needs_verification candidate, the lookup returns one of three outcomes. The conservative default treats only an unambiguous authoritative match as exact and sends everything else to the cataloguer, because surfacing a near match for human selection is always safe and a wrong auto-fill is the failure this stage exists to prevent.

What counts as exact versus near is a match-scoring decision (normalized exact-string match, versus a ranked or fuzzy match above a threshold). [verify] the specific scoring rule and any similarity threshold for your run and tune it per institution; the safe default is to auto-fill only an unambiguous match.

A fieldValue carries one authority_candidate, so the record holds no structured list of alternatives. When a lookup returns several plausible terms, the value keeps its single proposed candidate at needs_verification, and the alternatives live in review_flags for that record until the cataloguer settles them. Do not add a multi-candidate field to the value.

verified records the lookup's disposition; the human accepts separately

Setting authority_status to verified records that an authority lookup returned an unambiguous exact match. It is a separate act from the cataloguer accepting the value at stage 6. A value can be verified here and still be edited or rejected by the human, and the per-record gate in ../../docs/the-improvement-loop.md counts only the human verdict. Final authority over the record stays with the cataloguer.

Running it

The cataloguer runs this as its own step, separate from generation. The pattern is sample user prompt #4 from the pilot (../../Marketing_Branding/Automated Metadata Service/02-pilot-program/sample-user-prompts.md (in the initiative)):

For every subject and depicted_entity in ./output/telegrams/ marked needs_verification,
query id.loc.gov and FAST for the authorized term and URI. Where you find an exact
match, fill it in. Where the match is close but not exact, list the candidates and let
me choose. Where there's no match, flag it for manual entry. Do not guess URIs.

That instruction is the whole stage: it filters to needs_verification values, runs the deterministic lookups, applies the three dispositions, and refuses to invent identifiers. A run reports, per field, how many candidates were confirmed, how many surfaced as near matches, and how many found no match, so the cataloguer can see where the authority work concentrated before opening review.

Worked illustration: a creator value the generation stage proposed as Edgar Degas at high confidence, marked needs_verification with vocabulary LCNAF under value_id creator, resolves against LCNAF to the authorized heading. The skill fills its authority_uri and sets authority_status to verified; the cataloguer confirms at review. A creator the generation stage left null (no visible maker's mark) has no candidate, so this stage does nothing with it and the honest gap goes to the cataloguer. See the fuller version in ../../docs/authorities.md.

Adding a vocabulary

An institution extends the authority set itself. Sample user prompt #5 is the worked case: a library beginning to describe LGBTQ+ materials wires Homosaurus into this stage.

We're starting to describe LGBTQ+ materials and want to use Homosaurus for those
subjects. Add Homosaurus to the authority-resolution stage (homosaurus.org has a
linked-data API), add it to the vocabulary priority list in the application profile for
the relevant collections, and document how it's wired so the next person understands it.

Wiring a new authority means adding a lookup function for it (same deterministic shape as the others, endpoint [verify]ed against its published documentation), adding the vocabulary to controlled_vocabularies in the application profile so generation proposes candidates under it, and recording the wiring so the next operator can follow it.

This change splits by the generalizable-versus-domain test in ../../docs/the-improvement-loop.md. The resolution mechanism for a new source is generalizable, because any institution describing different works benefits from a new authority being resolvable; it contributes upstream to this repo. The institution's choice to prioritize that source for a given collection encodes local context and stays in its profile and overrides/.

What this stage never does

• It never invents a URI. An identifier is only ever echoed from what an authority lookup returned (hard rule 3 in ../../CLAUDE.md).
• It never runs a language model. The disposition is an ordinary lookup, which is what makes it reproducible: the same candidate against the same authority file returns the same result.
• It never resolves a sensitive or reparative-description case on its own. Those route to a human via review_flags at generation; see ../../docs/responsible-description.md.
• It never sets the human verdict. It dispositions the candidate; the cataloguer accepts the record.

Cross-references

• ../../docs/authorities.md: the design rationale, the full source table, and the determinism argument.
• ../../docs/architecture.md: the seven stages and where resolution sits.
• ../../docs/the-improvement-loop.md: how this stage runs each round and how the per-record gate counts the human verdict.
• ../../schemas/metadata-record.schema.json: the fieldValue contract this stage transitions.
• ../../schemas/application-profile.schema.json: where the vocabulary priority order and endpoints are configured.