# Research data dictionary — schema 1.0.0

## Entry points and identities

`data/graph.json` is the public research projection. `data/release-manifest.json` gives its release identity and SHA-256 hashes of each downloadable artifact. `data/record-contract.json` publishes the project's required fields and controlled vocabularies; it is a project contract, not a general JSON Schema dialect.

Top-level arrays are `works`, `documents`, `claims`, `evidence`, `relations`, `reviews`, and `evaluations`. Concepts and subcategories retain the existing matrix vocabulary. Existing work and essay IDs are unchanged. New `research-work-001`–`004` are catalogue representations of primary sources, not replacements for existing matrix cards. New claim/evidence/relation/review/evaluation IDs are sequential opaque identifiers. IDs are never reassigned after withdrawal.

Stable question links use `library/research/?r_view=claims&r_item=claims%3Aclaim-019`; works use `r_view=works` and their work ID. Surviving legacy evidence/relation links resolve to their question. Matrix essay links retain `?node=e1`, `e2`, and `e3`. The interface serializes only public view, q, domain, claim (framework-aspect selector), and item state. Historical administrative filter/comparison parameters are ignored by the interface. Withdrawn IDs are discarded. The shared export/query library retains legacy query functions for data consumers.

## Common fields

`visibility`: public, protected, or private. `lifecycle`: draft, active, superseded, or withdrawn. Only public active records are projected. `record_revision` is a positive integer incremented on a substantive record change; the release content hash additionally detects any changed payload. `review_ids` refer to named provenance records. Private dependencies suppress dependent public records; fields not in the public allowlist are omitted.

Unknown values are null or an explicit unchecked status. Dates are ISO dates; years are bibliographic years. Arrays preserve multiple values.

## Works and documents

Works identify publications: `work_id`, title, short_title, author/author_full (legacy display strings), citation, url, domain, branch_subcategories, concept_edges, and editorial summary. `publication_type`, `year`, and `edition_note` preserve catalogue classifications. Categories organize works; they are not evidential support edges. Legacy `framework_relevance`, `relation_type`, and `source_evidence` commentary is not included in the research projection.

`authors` is an array of structured given/family names or a literal organizational/unparsed name. A literal name is not guessed into personal components. `identifiers` has doi, arxiv, isbn; null means not established. `venue` is the consulted source's venue/container description; legacy detail may remain in citation. `issued` is a date-parts array such as [2020] or [2020,7]. `consulted_edition` identifies the version checked; `correction_status` distinguishes not_checked from an actual none_found check, corrected, retracted, or expression_of_concern. `rights` has license and notice; null license grants no new rights.

`assessment` separates bibliographic_check (unchecked, checked, conflicting/title reconciliation), evidence_access, locator_check, interpretation_review, checked_at, method, actor, source_url, and notes. Source author lists and dates may be normalized while preserving the stable identity and original citation. Mismatch flags mark records for reconciliation.

Documents are the three first-party canonical essays: document_id, title, public relative url, sha256, visibility, lifecycle. Their current byte hashes anchor evidence to a specific edition. A source replacement invalidates generation until the locators are checked again.

## Claims and evidence

Public claims have claim_id, label, statement, statement_mode (exact_text or editorial_paraphrase), kind, origin, argument, consequence, scope, attribution, concepts, question, topic, domain, order, research_use, and provenance/common fields. `question` is the visible inquiry; `topic` is its framework-aspect label; `research_use` specifies a concrete comparison or investigation. Each must be nonempty. At least two distinct scholarly works must connect directly, with at least one supports/provides_method_for relationship; unavailable dependencies suppress a stranded question. `argument` reconstructs the premise-to-conclusion connection; `consequence` identifies the resulting design or evaluation requirement. Both must be nonempty. `origin` names an available document and full-text evidence record with a page/text selector. Unresolved questions, generic qualifiers, empty assumptions, and opposition-search placeholders are excluded from the public projection. The record contract's `required` fields describe the private editing ledger; `public_fields` describes the downloadable projection.

Evidence has evidence_id, source_type (works/documents), source_id, url, edition, locator, paraphrase, access_basis, limitations, review_ids, and common fields. `edition` carries label, sha256 when locally established, and accessed_at. `locator` separates pdf_page (one-based), printed_page when known, section, paragraph when available, and text_selector. The selector is a short exact matching aid. External HTML/abstract sources use a null PDF hash.

`access_basis` means unavailable, metadata, abstract, or full_text. Full_text records identify the specified passage read. Optional `attributes` describe method, sample, outcome, assumptions, and replication_status. Support, challenge, qualification, evaluation, and implementation relations require abstract or full-text evidence.

## Relations

Each relation has relation_id, subject and object (each type/id), predicate, explanation, evidence_ids, attribution, scope, limitations, and review/common fields. Attribution is source_explicit, curator_inferred, or proposed_comparison. The current nine edges are direct work-to-claim editorial interpretations. `reading_role` supplies a concise visible explanation of the work’s role (such as Philosophical basis or Defeater analysis). The complete relationship explanation is displayed alongside the linked work. Public relations cite the originating passage for each claim endpoint and substantive evidence for each work endpoint.

| Predicate | Meaning |
|---|---|
| cites | Bibliographic reference |
| supports | Evidence or argument for a scoped proposition |
| challenges | A substantive reason against a scoped proposition or inference |
| qualifies | Restricts scope, assumptions, or interpretation |
| illustrates | Example or analogy |
| motivates | Supplies a reason to investigate |
| provides_method_for | A potentially applicable method |
| implements | Realizes a specified part, subject to stated evidence |
| evaluates | Assesses a specified target by an identified method |
| is_alternative_to | Competing account or method with stated target differences |
| depends_on | Logical or architectural prerequisite |

An absent edge means no relationship record has been entered.

## Reviews, proposals, and release

Reviews identify review_id, actor, method, checked_at, bibliographic_check, evidence_access, locator_check, interpretation_review, and notes. `agent_checked` and `human_reviewed` identify distinct review types. These fields capture entities, review activities, reviewers, and derivation. Version-linked page/text selectors follow the source/selector distinction described in [Web Annotation](https://www.w3.org/TR/annotation-model/).

Evaluations have evaluation_id, label, claim_ids, question, status, operational_definition, procedure, baseline, requirements, failure_conditions, limitations, and common fields. The evaluation array is currently empty: all standalone proposals have been withdrawn from publication. Concrete research-use instructions are part of the question records, not claims of completed experiments.

Release fields identify schema_version, UTC-date-based version, content_hash, citation, public counts, and review_notice. The content hash covers the public records before insertion of the release block; artifact hashes in the manifest cover complete file bytes. The manifest does not include itself, avoiding a recursive hash.

## Exports and encoding

BibTeX, RIS, and CSL-JSON contain bibliographic works. Graph JSON preserves works, claims, and other record types as separate entities. CSV provides nodes (works and claims), relations, and evidence; nested values use JSON strings. Review/document context is available in graph JSON.

Filtered work exports exactly match the visible work set. Exporting visible questions adds their one-hop relations and the source/evidence dependency closure. Referenced evidence, source documents/works, and reviews are included so no relationship dangles. Empty selections stay empty. Selection metadata documents this rule; full exports have the same public source as the interface.

CSV cells are quoted with doubled internal quotes. Cells beginning with a spreadsheet formula-triggering character (including after whitespace) receive an apostrophe prefix; this safety encoding does not alter canonical JSON values. RIS line breaks in field values are normalized to spaces. BibTeX special characters are escaped, Unicode is retained, and literal author names are brace-protected. Missing identifiers are omitted rather than guessed.

Reuse terms not specified; this export does not grant additional rights. Original documents, editorial annotations, metadata, and software are distinct rights contexts. No full third-party texts are added to the reusable exports.