# ORCHID bibliography: schema

Release `v2026.10`, bibliography 0.1. Generated by `tools/build_bibliography.py` (deterministic;
`--check`). Croissant-ready field descriptions: the column tables below (also in `parquet.json`).

## Ids

- Paper: `doi:<lowercase DOI>`; works without DOI `nodoi:<16 hex>` = sha256 of `folded first-author surname|year|folded
  title (or printed reference)`; `no_doi: true`. Literature ids of the same work (`ref:...`, `doi:...` in
  `literature/papers.json`) are listed in `aliases`.
- File key: `p` + first 16 hex of sha256(id); `papers/<key>.json`, `pages/papers/<key>.html`.
- Other nodes (edges only): `tdb:<file>` (a TDB file of the ORCHID catalog), `handbook:okamoto-2010:<SYS>` (the
  assessed diagram of a binary system in H. Okamoto, Desk Handbook: Phase Diagrams for Binary Alloys, 2nd ed., ASM International (2010)).
- Edge: `e` + first 16 hex of sha256(`type|src|dst|provenance source`).

## Paper record (`papers.jsonl`, `papers/<key>.json` -> `paper`)

| field | meaning |
|---|---|
| `id`, `key`, `doi`, `doi_url`, `id_basis`, `no_doi` | identifiers (above) |
| `title`, `subtitle`, `authors[{given, family, name, orcid, orcid_authenticated}]`, `container_title`, `container_title_short`, `volume`, `issue`, `pages`, `article_number`, `year`, `issued`, `publisher`, `type`, `issn[]`, `isbn[]`, `language` | Crossref metadata (`metadata_source: crossref`); otherwise the fields ORCHID's sources hold |
| `metadata_source` | `crossref` or the ORCHID source of the fields |
| `citation` | one-line citation; `citation_printed`: the reference as printed in an ORCHID source when it is not Crossref-derived |
| `crossref` | `{status, retrieved_at, references_deposited, references_count}` |
| `license[]` | Crossref `license` entries `{url, content_version, start, delay_in_days}` |
| `is_referenced_by_count`, `is_referenced_by_count_retrieved` | Crossref citation count and its retrieval date |
| `doi_match` | for DOIs matched from a printed reference (handbook source line, cited source of a value, TDB header): `verified` (Crossref first author = printed first author, accent-insensitive; year within +-1; title / journal not contradicting), `weak` (kept, flagged: author not first, year off but journal or volume/page agreeing, journal unconfirmed), `unverifiable` (no Crossref record); `mismatch` on a no-DOI record whose matched DOI was dropped; null when the DOI was not matched from print |
| `doi_check` | details of `doi_match`: `{status, issues[], evidence{author, year, title, journal, volume_page}, basis, sources_checked[]}`; on dropped matches `rejected_dois[]` |
| `systems[]` | chemical systems (sorted element symbols joined by `-`) |
| `candidate_systems_inferred` | discovery leads: candidate systems from citation closures, with basis (hypotheses; not in `systems`) |
| `roles[]`, `role_details{}` | roles (below) and their details |
| `evidence_summary` | `reported` (values read from this paper: `n_values`, `n_values_accepted`, `by_evidence_class`, `by_property_group`, `by_property`, `n_tables`, `n_text_passages`, `n_figures` (0: no released value comes from a figure)), `reader_agreement` (`by_reader_tier`, `by_reader_agreement` when the release carries it), `cited_as_source` (values in other papers citing it: counts as above and `n_citing_papers`), `espei_datasets[]` (paths in the ESPEI bundle), `phase_registry_phases[]`, `assessed_assemblage_records` |
| `availability` | `open_access_license` (`{url, content_version, start, delay_in_days, basis: crossref_license_field}` or null), `read_by_orchid` (`yes`/`no`), `read_detail[]` (`values_extracted`, `processed_no_released_values`, `full_text_screened_for_origin`), `pdf_redistributed: false` |
| `aliases[]`, `provenance[]` | literature ids of the same work; inputs that contributed to the record |
| `relation_counts` | `{edge type: {out, in}}` |
| `urls` | `json`, `html` |

`papers/<key>.json` adds `relations[]`: `{direction: out|in, type, edge_id, other{id, key, doi, title, year, roles}, count, provenance, attrs}`.

## Roles

| role | meaning, source |
|---|---|
| `corpus_assessment_read` | ORCHID processed the paper's full text (SGTE-corpus census) and/or released values read from it (`literature/papers.json` reporting paper); `values_released` |
| `cited_original_source` | cited by a paper ORCHID read as the source of a value (`cited_sources` of the literature records) |
| `tdb_source_assessment` | the assessment a TDB file's header cites (SGTE collection: header citation matched to the Hallstedt 2025 reference list, `tdb_pdf_links.json`); also literature model links and hand-verified assessments. `tdb_files[{file, path, sha256, bundled, system, link_status, link_match, basis}]` |
| `tdb_compilation` | the publication of a TDB collection (Hallstedt 2025, SGTE binary collection) |
| `handbook_diagram_source` | original evaluation printed under an assessed diagram of H. Okamoto, Desk Handbook: Phase Diagrams for Binary Alloys, 2nd ed., ASM International (2010); `systems` (citations only; no handbook text) |
| `discovery_lead` | found by the Crossref higher-order assessment discovery (`open-tdb` branch `discovery/forward-citations`, `catalog/discovery/higher-order-assessment-targets.json`), not read: `rank`, `score`, `max_order`, `systems_named_in_title`, `candidate_systems_inferred`, `discovery_sources`, `license_review` |
| `context_source` | same-system context source (none in this release) |
| `espei_reference` | cited by an ESPEI dataset and not otherwise known |

## Edges (`edges.jsonl`)

`{id, type, src, dst, src_kind, dst_kind, count, provenance{source, dataset, method, ...}, attrs{}}`

| type | meaning |
|---|---|
| `cites` | paper ORCHID read -> work printed as the source of its values; `count` = values carrying that citation; `attrs`: `n_values_accepted`, `evidence_class`, `citation_status` (resolved / author_mismatch / surname_mismatch), `property`, `systems` |
| `used_in_assessment` | inverse of `cites`: original data paper -> the paper (assessment) that used it, same attributes |
| `models_system_in_tdb` | paper -> `tdb:<file>`; `system`, `tdb_sha256`, link status |
| `reassesses` | later assessment -> earlier assessment of the same exact system; only when the later cites the earlier (`citation_basis`: orchid_extraction and/or crossref_reference_list) and both have a TDB of that system; method `citation+same-system` |
| `handbook_reproduces` | `handbook:okamoto-2010:<SYS>` -> original evaluation; `page`, `doi_matched_by` |
| `cited_by_crossref` | src's publisher-deposited Crossref reference list contains dst (both in this bibliography); `doi_asserted_by`; kept apart from ORCHID's own extraction |

## Flat tables

### papers.csv / papers.parquet

| column | type | description |
|---|---|---|
| `id` | sc:Text | Stable bibliography id: 'doi:<lowercase DOI>' or 'nodoi:<16 hex>' (sha256 of folded first-author surname|year|folded title or printed reference). Primary key. |
| `key` | sc:Text | URL-safe file key: 'p' + first 16 hex of sha256(id). Record at papers/<key>.json, page at pages/papers/<key>.html. |
| `doi` | sc:Text | DOI in lower case (empty when the work has none). |
| `no_doi` | sc:Boolean | True when the work has no DOI and the id is derived from first author, year and title. |
| `title` | sc:Text | Title (Crossref; for works without a Crossref record: the title held by ORCHID's sources, may be empty). |
| `authors` | sc:Text | Authors as 'Given Family', '; '-joined, in Crossref order. |
| `orcids` | sc:Text | ORCID iDs deposited with Crossref for the authors, '; '-joined. |
| `container_title` | sc:Text | Journal, book or proceedings title. |
| `volume` | sc:Text | Volume. |
| `issue` | sc:Text | Issue. |
| `pages` | sc:Text | Page range or article number. |
| `year` | sc:Integer | Publication year (Crossref 'issued'; otherwise as printed). |
| `publisher` | sc:Text | Publisher (Crossref). |
| `type` | sc:Text | Crossref work type (journal-article, book-chapter, ...). |
| `metadata_source` | sc:Text | Where the bibliographic fields come from: 'crossref', or the ORCHID source that printed the reference (orchid_literature_printed_reference, tdb_header, handbook_reference, discovery_snapshot, ...). |
| `citation` | sc:Text | One-line citation built from the metadata (printed reference for works without a Crossref record). |
| `systems` | sc:Text | Chemical systems the work covers in ORCHID (sorted element symbols joined by '-'), ';'-joined. Discovery leads contribute only systems named in their title. |
| `roles` | sc:Text | Roles in ORCHID, ';'-joined: corpus_assessment_read, cited_original_source, tdb_source_assessment, tdb_compilation, handbook_diagram_source, discovery_lead, context_source, espei_reference. |
| `tdb_files` | sc:Text | TDB files whose header cites this work as the assessment (tdb_source_assessment), ';'-joined. |
| `handbook_systems` | sc:Text | Systems whose assessed (handbook) diagram names this work as its source, ';'-joined. |
| `discovery_rank` | sc:Integer | Rank in the Crossref higher-order assessment discovery (discovery_lead). |
| `values_reported` | sc:Integer | Literature values ORCHID read from this paper (all released records, accepted or not). |
| `values_reported_accepted` | sc:Integer | Of those, values with flags.extraction_accepted. |
| `values_reported_experimental` | sc:Integer | Values read from this paper with evidence class experimental. |
| `values_reported_model` | sc:Integer | ... evidence class model. |
| `values_reported_dft` | sc:Integer | ... evidence class dft. |
| `values_reported_unspecified` | sc:Integer | ... evidence class unspecified. |
| `values_cited` | sc:Integer | Values in other papers whose printed source (cited_sources) is this work. |
| `values_cited_accepted` | sc:Integer | Of those, accepted values. |
| `property_groups` | sc:Text | Property groups of the values reported in or citing this work, ';'-joined. |
| `properties` | sc:Text | Property codes (HM_FORM, INVARIANT_TEMPERATURE, ...) of those values, ';'-joined. |
| `n_tables` | sc:Integer | Distinct tables of this paper the released values come from. |
| `n_text_passages` | sc:Integer | Distinct sentences (running-text quotes) of this paper the released values come from. |
| `n_espei_datasets` | sc:Integer | ESPEI datasets of the ORCHID bundle derived from values of this work (paths in papers.jsonl). |
| `n_phase_registry_phases` | sc:Integer | Phase-registry phases that cite this work (paper label or reference). |
| `n_assessed_assemblage_records` | sc:Integer | Assessed phase-assemblage records whose original evaluation is this work. |
| `open_access_license` | sc:URL | First Creative Commons licence URL in the Crossref license field (empty: none deposited). Never inferred from elsewhere. |
| `license_urls` | sc:Text | Every licence URL in the Crossref license field (TDM, publisher, CC), ';'-joined. |
| `is_referenced_by_count` | sc:Integer | Crossref is-referenced-by-count on the retrieval date. |
| `is_referenced_by_count_retrieved` | sc:Date | Date the Crossref record was retrieved. |
| `crossref_status` | sc:Text | found | not_found (404 at Crossref) | no_doi | not_fetched. |
| `doi_match` | sc:Text | For DOIs matched from a printed reference (handbook source lines, cited sources of values, TDB header citations): verified | weak | unverifiable (Crossref has no record), from comparing the Crossref first author (accent-insensitive), year (+-1), title and journal with the printed reference; mismatch on no-DOI records whose matched DOI was dropped (DOI_MISMATCHES.md). Empty: DOI not matched from a printed reference. |
| `read_by_orchid` | sc:Text | yes: ORCHID processed the paper's full text in its extraction corpus; no otherwise. |
| `edges_out` | sc:Integer | Edges with this paper as src (edges.*). |
| `edges_in` | sc:Integer | Edges with this paper as dst. |
| `json_url` | sc:URL | Resolvable JSON record of this paper. |
| `html_url` | sc:URL | Static HTML page of this paper. |

### edges.csv / edges.parquet

| column | type | description |
|---|---|---|
| `id` | sc:Text | Stable edge id: 'e' + first 16 hex of sha256(type|src|dst|provenance source). Primary key. |
| `type` | sc:Text | cites | used_in_assessment | models_system_in_tdb | reassesses | handbook_reproduces | cited_by_crossref. |
| `src` | sc:Text | Source node id (paper id, or handbook:okamoto-2010:<SYS> for handbook_reproduces). |
| `dst` | sc:Text | Target node id (paper id, or tdb:<file> for models_system_in_tdb). |
| `src_kind` | sc:Text | paper | handbook_diagram. |
| `dst_kind` | sc:Text | paper | tdb_file. |
| `count` | sc:Integer | cites / used_in_assessment: number of values carrying that citation. |
| `provenance_source` | sc:Text | orchid_extraction | crossref_reference_list | sgte_tdb_header | orchid_literature_model_link | verified_assessment | okamoto_handbook_source_line | citation+same-system. |
| `provenance_dataset` | sc:Text | Input the edge was read from. |
| `provenance_method` | sc:Text | How the edge was established. |
| `systems` | sc:Text | Chemical system(s) of the edge, ';'-joined. |
| `attrs` | sc:Text | Remaining attributes as compact JSON (evidence-class and citation-status counts, TDB sha256, page, ...). |

## Licence

Crossref metadata CC0; ORCHID-derived fields CC BY 4.0.