Institutional Documentation

Metadata and Provenance Schema

Schema version 1.0. Adopted 2026-05-12.

Every item in America's School Trust Library — every statute, every court filing, every Bates-stamped discovery page, every scholarly reference, every photograph, every Reading Room essay — carries a structured metadata record. The record names what the item is, where it came from, how to cite it, and what rights apply. It records who verified the metadata and how confident the Library is in the underlying claim. The schema is versioned, applied consistently across catalog records and primary sources, and intended to be machine-readable as well as human-readable. This page is the spec. Contributors and institutional partners write to it; researchers can read against it; reviewers can audit by it.

The core record

Every record in the Library, regardless of item kind, carries the following fields. All are required.

• title — the canonical title of the item. For statutes and cases, the standard short form (e.g., "Oregon Admissions Act of 1859"; "Wood v. Honeyman"). For discovery, the document's actual title as produced. For contributions, the title the contributor gives the work.
• slug — the URL fragment used as the page's locator. Lowercase, hyphenated, ASCII. Stable for the life of the record; slug changes require a redirect.
• kind — one of: statute, case, discovery, scholarship, contribution, multimedia. The vocabulary is closed at v1.0.
• primary_source_citation — the citation by which the item is referenced in legal or scholarly writing. A statutory pin (Stat./U.S.C./ORS), a reporter citation (volume, reporter, page), a Bates pin range, an archival call number, a journal citation, or equivalent. If no formal citation exists (a contributor's photograph, for instance), the value is none and the provenance note carries the locator.
• provenance_note — one paragraph explaining how the item was acquired and verified. See the provenance schema section below.
• rights_status — one of: public_domain, licensed, library_authored, cited_not_redistributed, unclear_rights_held_back. Where licensed, the license is named (e.g., CC BY-SA 4.0).
• confidence — one of: verified, partial, pending, contested. See the confidence vocabulary section.
• last_reviewed — ISO date (YYYY-MM-DD) of the most recent review by a librarian. Updated on every substantive review, not on cosmetic edits.
• librarian_of_record — the name (or named role, for institutional records) of the librarian who owns this record and is responsible for its accuracy.

A record missing any required field does not validate. The Library does not publish records that do not validate.

Per-kind extensions

Each item kind adds required and optional fields beyond the core record. The per-kind vocabulary is closed at v1.0 and listed here for reference.

Statute

• jurisdiction (required) — the issuing government (e.g., US, Oregon, Coos County).
• code_citation (required) — the citation within the jurisdiction's code (e.g., ORS 327.405; 11 Stat. 383, sec. 4).
• effective_date (required) — ISO date the statute took effect.
• repealed_date (optional) — ISO date the statute was repealed, if applicable. Absent means in force.

Case

• court (required) — the deciding court (e.g., Oregon Court of Appeals; Coos County Circuit Court).
• docket (required) — the docket number (e.g., S072734; 24CV38372).
• decided_date (required) — ISO date of the decision or order.
• reporter (optional) — reporter citation if published (e.g., 380 Or. 1).
• precedential (required) — boolean. Whether the decision binds future cases in that court.

Discovery

• bates_pin_range (required) — the Bates range produced (e.g., OREGON_DSL_004112 – OREGON_DSL_004158).
• producing_party (required) — the party who produced the document.
• protective_order (required) — reference to the protective order governing the document, or none. Documents marked confidential under a protective order are not published; the record exists for catalog completeness.

Scholarship

• author (required) — one or more authors, surname first. Multi-author works list all authors.
• publication_year (required) — year of publication.
• publisher (required) — the publishing house, journal, or institution.
• peer_reviewed (required) — boolean. Peer-reviewed journal articles are marked true; reports, monographs, and white papers are marked false.

Contribution

• contributor (required) — the contributing person or institution.
• contribution_date (required) — ISO date of contribution.
• editorial_status (required) — one of: accepted, under_review, revisions_requested.

Multimedia

• format (required) — file format and codec where relevant (e.g., image/jpeg; video/mp4).
• dimensions (required for image and video) — pixel dimensions (e.g., 1920x1080).
• rights_clearance (required) — cleared, claimed_fair_use, commissioned, or held_back.
• commissioned_by_library (required) — boolean. True for work the Library commissioned and now owns.

Records may carry kind-specific optional fields beyond these, but the listed fields are the floor.

Provenance schema

The provenance_note field carries a paragraph of narrative; behind it the record carries four structured provenance subfields. All are required where they apply.

• acquisition_path — how the item entered the Library. One of: purchased, donated, public_records_request, discovery_production, contributed, scraped, library_authored. Where applicable, the source is named (e.g., scraped from https://oregonlegislature.gov/...).
• verification_path — who verified the metadata and what they checked. Names the verifying librarian, the date, and the specific fields verified (e.g., "Citation and effective date verified against Oregon Legislative Assembly online statute database, 2026-04-15, by [librarian name].").
• chain_of_custody — narrative chain where one is needed. Required for discovery productions, donated materials with provenance significance, and any item whose authenticity could be questioned. May be empty for items whose chain is self-evident (e.g., a statute scraped from a state legislature's website).
• relationships — links to other items in the Library. The relationship vocabulary is closed at v1.0 and small by design: cites, is_cited_by, supersedes, superseded_by, discusses, is_discussed_in. Each relationship names the slug of the related record.

The closed relationship vocabulary is deliberate. A larger vocabulary would invite inconsistency; six terms cover the citation, supersession, and discussion patterns the Library's items actually exhibit.

Confidence vocabulary

The confidence field takes one of four values. Confidence is visible to readers on the page as a badge.

• verified — primary source in hand; two independent verifications on file; no known dispute. The default standard for statutes, reported cases, and items the Library has worked from for more than one deliverable.
• partial — primary source in hand for part of the claim; remainder pending. Used when a record's core facts are verified but secondary fields (e.g., a date, an attribution) remain unconfirmed.
• pending — primary source in process of acquisition. The record exists because the item is cataloged and named, but verification has not yet completed. Pending records are visible but flagged.
• contested — two reputable sources disagree, or a rights holder has raised a dispute the Library has not resolved. Contested records are not retracted; the disagreement is named on the page.

Confidence is the field most likely to change over an item's life. Movement from pending to verified is routine; movement from verified to contested is rare but consequential, and updates last_reviewed.

Versioning

The schema is versioned. Current version: 1.0, dated 2026-05-12.

Schema changes that add new optional fields, or add new values to an open vocabulary, are backwards-compatible and bump the minor version (1.0 → 1.1). Records written under the prior minor version continue to validate without modification.

Schema changes that remove a field, rename a field, or remove a value from a closed vocabulary require a migration plan and bump the major version (1.x → 2.0). Old records continue to validate against the version they were created under until the migration is run. Major-version migrations are announced on the pro site at least thirty days before the new version takes effect.

Every page in the Library declares the schema version its record conforms to. Federation partners can rely on the declared version when reading.

Where the schema lives, machine-readable

The canonical machine-readable spec lives at /pro/metadata-schema/v1.json in JSON Schema format (draft 2020-12).

Pages declare their schema version in a schema_version field at the head of the record (e.g., schema_version: "1.0"). Federation partners and external tools can pull /pro/metadata-schema/v1.json directly.

How to validate a record

For contributors and institutional partners writing records, the validation steps are short.

1. Confirm every required core field is present and non-empty.
2. Confirm every required per-kind field for the record's kind is present and non-empty.
3. Confirm field formats match the spec — ISO dates for date fields; closed-vocabulary values drawn only from the listed terms; slugs lowercase and hyphenated.
4. Confirm the confidence value is one of the four allowed terms.
5. Confirm the provenance record is present: acquisition_path filled; verification_path names the verifier and the date; chain_of_custody present where applicable; relationships listed where applicable.

Records that fail validation are returned to the contributor with the failing field named. The Library's librarian of record for the relevant section is named on the response.