Offline Bibliography Metadata Check
Use Python 3.10+ from a monorepo checkout. No installation, API credentials or network access is required:
python3 apps/wiki/scripts/check_research_citations.py apps/wiki/scripts/fixtures/csl/good.jsonpython3 apps/wiki/scripts/check_research_citations.py apps/wiki/scripts/fixtures/csl/dup.jsonpython3 -m unittest discover -s apps/wiki/scripts/tests -p 'test_research_citations.py' -vThe good fixture returns exit 0 and ok: true. The duplicate fixture returns
exit 1 with findings for record a, fields id and DOI. The tests also cover
invalid calendar dates/components, missing locators, Unicode, explicit unknown
versus omitted dates, malformed records, and audit guards against sockets and
writes. The tool reads only the selected bibliography and never rewrites it.
Supported subset
Section titled “Supported subset”The input is a JSON array of objects, using these fields:
| Field | Required metadata |
|---|---|
id | A nonblank string identifier, unique within the selected file. |
title | A nonblank string. |
author | A nonempty array of name objects, each with a nonblank string family, given or literal. Use literal for organization authors. |
organization | Optional nonblank string alternative when no author array is supplied (a local subset extension). A publisher alone does not identify an author. |
issued | {"date-parts": [[year]]}, [[year, month]] or [[year, month, day]] within that object. Exactly one date is supported; all supplied components must be integers, not Booleans. Years are 1–9999, months 1–12, and complete dates must exist on the Gregorian calendar. |
issued: "unknown" | Explicitly marks an unknown date in this local subset. An omitted issued is a missing-field finding, not an unknown date. |
DOI or URL | At least one source locator: a DOI matching 10. plus 4–9 digits, / and a non-whitespace suffix, or an absolute HTTP(S) URL with a hostname and no embedded credentials. Lowercase doi is also accepted. |
This is not a full CSL validator. Date ranges, seasons, BCE dates, numeric IDs, ISBN-only locators and other CSL encodings are outside the documented subset; review those records explicitly rather than treating this checker as a universal Zotero export validator. Other fields are left untouched and unvalidated.
DOI comparison removes a leading doi:, https://doi.org/ or
http://dx.doi.org/ (HTTP/HTTPS variants accepted), trims surrounding whitespace,
and ignores case. Thus 10.1000/EXAMPLE and
https://doi.org/10.1000/example produce a duplicate finding. DOI/URL syntax is
checked locally: no identifier is resolved, and no source’s existence,
authorship, accuracy or availability is established.
Interpret findings
Section titled “Interpret findings”Each finding contains record, field and message. A record with no usable
ID is identified by its zero-based index:N; a duplicate points to the earlier
record’s index. A malformed or missing locator uses field locator.
Exit 1 means at least one finding or an unreadable/malformed JSON file. Exit 2 means incorrect CLI usage. Output is deterministic JSON; Unicode input bytes are preserved because the input is never modified. Resolve duplicate IDs without inventing citation facts, add missing metadata from the actual source, and mark an unknown date explicitly rather than substituting a guessed year.
Return to Research Citations for citation and reference-management guidance.