Repository Public Research preview
1# Statuses, verdicts and thresholds23Everything below describes what `scripts/scholarly.mjs` computes. The comparisons are string4heuristics: they are documented so a reader can overrule them with the evidence each result5carries (`comparison` holds the claimed and the registered value of every field).67## How a reference is checked891. **Identifier first.** A cited DOI is looked up at Crossref; if Crossref does not know it, at10 doi.org, which covers every registration agency (DataCite, mEDRA, ...). arXiv DOIs and arXiv11 ids go to the arXiv API.122. **Comparison.** The cited fields are compared with the record (table below).133. **No identifier, or a DOI that does not resolve.** Crossref is searched with the whole14 reference; each candidate is judged; arXiv is searched by title when Crossref has no confident15 candidate.164. **Notices.** Crossref update notices attached to the record are read for retractions,17 expressions of concern and corrections.1819## Field comparison2021| Field | `match` | Warning | `mismatch` |22|---|---|---|---|23| Title | similarity >= 0.9 | `close`: 0.75 to 0.9 | below 0.75 |24| First author | same family name as the record's first author | `order_differs`: an author of the record, not the first | not an author of the record |25| Authors (when several are cited) | all cited authors are in the record, same count | `count_differs` | a cited author is absent from the record |26| Year | equal | `off_by_one` | differs by 2 or more |27| Venue | equal, abbreviation, or acronym | `differs` | never a mismatch |28| Volume, first page | equal | `differs` | never a mismatch |2930- **Title similarity** is the Sørensen-Dice coefficient on title words after lower-casing,31 removing accents, punctuation, markup and stop words, and a leading "RETRACTED:", "Erratum to:"32 or similar. A title that equals the other one plus a subtitle counts as 0.9.33- **Family names** are compared after removing accents; particles stay with the name ("van der34 Waals"); initials and noisy index entries ("Tim Bollerslev B") are tolerated.35- **Venue** tolerates abbreviations ("J. Financ. Econ.") and acronyms ("JFE"). Venue, volume and36 pages never produce a mismatch alone, because styles and registries disagree on them37 routinely.38- **Year off by one** is a warning because online-first and issue years differ legitimately.3940Verdict: `mismatch` when any field mismatches, `minor_differences` when there are only41warnings, `match` otherwise.4243## Statuses of `verify-doi`4445| Status | Condition |46|---|---|47| `invalid_doi` | The string is not a DOI (`10.<4-9 digits>/<suffix>`) |48| `not_found` | Neither Crossref nor doi.org knows the DOI |49| `doi_resolves_unchecked` | The DOI resolves, but neither a title nor both author and year were supplied |50| `metadata_mismatch` | The DOI resolves and the verdict is `mismatch` |51| `retracted` | The record carries a retraction, withdrawal or removal notice (wins over the others) |52| `verified` | The DOI resolves and the verdict is `match` or `minor_differences` |5354## Statuses of `verify-bib`5556One per entry: `verified`, `doi_missing_found`, `metadata_mismatch`, `doi_not_found`,57`doi_invalid`, `ambiguous`, `not_found`, `retracted`, `unverifiable`, `error`. The meaning of58each and what to do is in the table of `SKILL.md`. Details that matter:5960- `doi_not_found` with `suggested_doi`: the cited DOI does not exist, and a record with the same61 title plus author or year exists under another DOI. Typical of a mistyped or invented DOI on a62 real paper. Without `suggested_doi`, neither the DOI nor the title was found.63- `doi_missing_found`: the entry had no DOI and exactly this rule held: title similarity >= 0.964 and the first author or the year agrees, with neither contradicting. `alternatives` lists65 other records that also satisfy it (a reprint, a preprint and its published version).66- `ambiguous`: at least one record has a similar title (>= 0.75) but fails the rule above.67- `error`: a registry timed out, rate limited or failed. The entry was not checked.6869The report also gives `duplicates` (one DOI under several citation keys), `parse_errors`70(BibTeX syntax errors with line numbers) and `needs_attention` (keys of every entry that is71neither `verified` nor `doi_missing_found`).7273## Confident match for a search candidate7475A candidate is accepted only when all of these hold:7677- the title agrees: similarity >= 0.9, or, for a raw reference whose title could not be isolated,78 at least 90 % of the candidate's title words appear in the reference;79- the first author agrees or the year agrees (within one year);80- neither the first author nor the year contradicts;81- for titles of fewer than three significant words ("Introduction", "Editorial"), both the82 author and the year agree.8384This is deliberately strict. It prefers `ambiguous` to a wrong match, because a wrong match85turns into a wrong DOI in someone's bibliography.8687## Known weaknesses8889- Two different papers with the same title, first author and year (a conference paper and its90 journal extension) cannot be told apart: both appear, one as `match`, the other in91 `alternatives`.92- Titles in non-Latin scripts fold to few or no comparable words; results for them are unreliable.93- A reference whose free text does not follow a common style may be split badly into fields.94 The whole string is still sent to the registry search, and the title-word rule above applies.95- Crossref metadata has errors of its own. A `metadata_mismatch` means the citation and the96 registry disagree, not that the citation is the one in error.97