---
id: guide-schema
type: guide
title: Record Schema, Evidence Tiers, and Verification Levels
updated: 2026-10-19
canonical_url: https://research.breacher.ai/guides/schema.md
---

# Record Schema, Evidence Tiers, and Verification Levels

> Field definitions for source records (`/sources/*.md`, `/data/studies.json`) and metareports (`/metareports/*.md`).

## Source record fields {#source-fields}

| Field | Type | Description |
|---|---|---|
| `id` | string | Stable slug `firstauthor-year-keyword`. Never reused. |
| `title` | string | Exact paper title |
| `authors` | string[] | Author names in order. `et al.` marks an incomplete list. |
| `year` | int | Publication year |
| `venue` | string | Journal or conference |
| `volume` | string \| null | Volume (issue) |
| `pages` | string \| null | Pages or article number |
| `doi` | string \| null | DOI without the `https://doi.org/` prefix. `null` means unknown or not yet verified. |
| `url` | string \| null | Canonical URL when there is no DOI (for example arXiv) |
| `pmid` | string \| null | PubMed ID, recorded only when shown in the record that was read |
| `pmcid` | string \| null | PubMed Central ID (`PMC…`), recorded only when seen |
| `arxiv_id` | string \| null | arXiv identifier, recorded only when seen |
| `openalex_id` | string \| null | OpenAlex work ID (`W…`), recorded only when seen |
| `oa_url` | string \| null | Open-access full-text URL, if one was listed in the record read |
| `peer_review` | enum | `peer-reviewed-journal`, `peer-reviewed-conference`, `preprint`, `industry`, `essay` |
| `evidence_tier` | enum | `A`–`E`; see [tiers](#tiers) |
| `design` | string | Study design summary |
| `modality` | string[] | `image-face`, `image-general`, `video`, `audio`, `text`, `audiovisual`, `robot-face`, `cg-face`, `vr-avatar`, `review`, … |
| `stimuli` | string | What participants saw or heard, including the generator |
| `n_participants` | int \| null | Total participants across experiments |
| `n_note` | string | Breakdown or caveats for N |
| `topics` | string[] | Topic tags |
| `summary` | string | One-sentence bottom line |
| `results` | object[] | `{metric, value, note, source_location}`. `≈` marks an approximate value. `source_location` is where the value was read: `abstract`, `full text`, or a section/table such as `Results, Table 2`; `null` when not recorded. |
| `moderators` | string[] | Factors that changed the effect |
| `limitations` | string[] | Main limitations |
| `mechanism_supported` | string[] | Uncanny-valley records only: mechanisms the study supports or argues against |
| `verification` | object | `{status, confidence, checked, via}`; see [verification](#verification) |
| `cited_in` | string[] | Metareport IDs that cite this record (generated) |

## Metareport fields {#metareport-fields}

| Field | Description |
|---|---|
| `id` | `MR-NNNN`, stable |
| `slug` | URL slug, stable |
| `question` | The research question the report answers |
| `version` | Semantic version. Minor = new findings or sources; patch = corrections or verification upgrades. |
| `published` / `updated` | ISO dates |
| `status` | `seed-partially-verified`, `verified`, `superseded` |
| `method` | `narrative-synthesis` or `meta-analysis` |
| `sources` | Source IDs used |
| `related` | Related metareport IDs |

Finding IDs take the form `MR-NNNN.Fn`. Confidence levels for findings:

- **High:** consistent across three or more independent peer-reviewed studies.
- **Moderate:** consistent, but with fewer studies, high heterogeneity, or values pending verification.
- **Low:** a single study, or unverified details.

## Evidence tiers {#tiers}

| Tier | Definition |
|---|---|
| A | Peer-reviewed meta-analysis or systematic review |
| B | Peer-reviewed primary empirical study |
| C | Peer-reviewed narrative review, theory or essay |
| D | Preprint (not peer reviewed) |
| E | Industry or grey literature |

## Verification levels {#verification}

| Status | Definition |
|---|---|
| `verified-fulltext` | Every recorded value was checked against the full text. `via` names the copy used. |
| `verified-abstract` | Values checked against the official abstract (publisher, Semantic Scholar or arXiv). Any value not in the abstract is noted on the record. |
| `verified-doi` | The DOI was confirmed to resolve to the stated publisher record; values have not been checked. |
| `unverified` | Values are pending a check against the primary source. `confidence` gives the compiler's prior. |

## Citations file {#citations-file}

`/data/citations.json` is the single file for independent verification. It is generated by the build from `data/studies.yaml` and the metareports' findings tables, and contains every record, cited or not, whatever its verification status.

| Field | Description |
|---|---|
| `schema_version`, `generated`, `site_version`, `license`, `count`, `canonical_url` | File metadata; `count` equals the number of source records |
| `how_to_verify` | Plain-text procedure for checking claims against the original papers |
| `sources[]` | Sorted by `id`. Each has `id`, `citation` (APA-style), `title`, `authors`, `year`, `venue`, `volume`, `pages`, `doi`, `doi_url`, `url`, `pmid`, `pmcid`, `arxiv_id`, `openalex_id`, `oa_url`, `resolvers` (URLs built only from known identifiers), `search_query` (`"<exact title>" <first-author surname> <year>`), `peer_review`, `evidence_tier`, `design`, `n_participants`, `claims[]` (`metric`, `value`, `note`, `source_location`), `verification` (`status`, `checked`, `via`), `cited_by[]` (`metareport_id`, `metareport_url`, `finding_ids`), `record_url` |
| `findings[]` | Every `MR-NNNN.Fn`: `id`, `metareport_id`, `text`, `confidence`, `source_ids`, `status` (`current` or `revised`), `revised` (dates) |
| `metareports[]` | `id`, `title`, `url`, `version`, `updated`, `source_ids` |

Links of the form `/data/citations.json#<id>` name the `sources` entry whose `id` is `<id>`. URLs beginning with `/` are relative to the site root.