Open science conventions · June 2026

fair.md & trust.md — manifests for FAIR data and epistemic trust

Two root files. One declares how findable and reusable your data is. The other declares how much to trust it.

Damien Huzard, PhD · Neuronautix

The problem

Science writing mixes statement types — and rarely says so

What goes unmarked

Cited fact, inference, and opinion look identical on the page

FAIR is widely endorsed; self-declaration is rare

AI-assisted drafts blur provenance further

No lightweight, conventional place to state a repo's FAIR posture

What readers need

Can I find and reuse this? (FAIR)

How much should I trust it? (epistemic)

Who or what produced it, and under what review?

Machine-readable, so crawlers can harvest it too

The idea

Two readable root files — one for data, one for trust

Place fair.md and trust.md at the root of any repository. Each is a YAML front-matter block (machine-readable) + plain English prose (human-readable). Together they answer both questions in under five seconds.

fair.md — what it declares

An honest FAIR self-assessment, not a certified audit

Data resources What FAIR objects the repo holds — path, type, topics, count

FAIR assessment Each F/A/I/R sub-principle rated yes · partial · planned · no · n/a

Identifiers & maintainers Canonical URL, ORCID, repository, DOI (if minted)

Companions Front door to trust.md, sitemap.xml, CITATION.cff, codemeta.json, RO-Crate

Maturity & last reviewed prototype · beta · stable · ISO date — so gaps are trackable, not hidden

fair.md — format snapshot

YAML front-matter + prose

fair.md — YAML block (excerpt)

fair_md_version: "0.1"
fair_assessment:
  findable:
    F1_globally_unique_persistent_id: "partial"   # HTTPS URLs; no DOIs yet
    F4_indexed_searchable:            "yes"       # sitemap.xml + robots.txt
  reusable:
    R1.1_clear_data_usage_license:    "planned"   # honest gap — not hidden
    R1.2_detailed_provenance:         "yes"       # see /trust.md
companions:
  trust: "/trust.md"
  ro_crate: "/ro-crate-metadata.json"  # recommended

trust.md — what it declares

Epistemic provenance at repository level

Authorship provenance

Named human authors + ORCID

AI agent roles + oversight policy

No-fabricated-citations governance

Correction and conflict-of-interest policy

Epistemic grading model

5 claim categories (cited → view)

0–100 confidence scale, 5 bands

Inline markup spec (Trust Lens)

Corpus-level stats, auto-derivable

trust.md — epistemic categories

Five types of claim, always distinguished

53 %

Cited

Directly supported by a cited source

22 %

View

Explicit interpretation, position, or normative conclusion

19 %

Inference

Reasoned from one or more sources; not stated verbatim

3 %

Consensus

Widely accepted domain knowledge or standard definitions

3 %

Hypothesis

Forward-looking or speculative claim

Percentages from this repository's corpus of 440 graded claims.

trust.md — confidence scale

0–100, five bands — independent of category

90–100 Very high Directly stated in a primary, peer-reviewed, or regulatory source

70–89 High Stated in a cited source; secondary or lightly interpreted

50–69 Moderate Reasonable inference, or consensus without a pinpoint citation

30–49 Tentative Plausible forward-looking claim with partial support

0–29 Speculative Normative, opinion, or vision claim with little direct evidence

Lineage — prior art and related standards

Builds on, does not replace

llms.txt

Root Markdown for machines — fair.md borrows ergonomics

codemeta / CITATION.cff

Rich machine-readable metadata — fair.md links to them

RO-Crate / FAIR Signposting

FAIR Digital Object packaging — fair.md is the front door

trust.txt (JournalList)

Org relationships — trust.md is epistemic status, distinct

W3C PROV / PAV

Provenance & authoring — trust.md aligns at corpus level

Nanopublications

Assertion + provenance + pub info — per-claim cousin

SEPIO / ECO

Formal evidence ontologies — trust.md is lightweight companion

ClaimReview

schema.org — path to harvestable JSON-LD per graded claim

Worked example — this repository

Real numbers from neuronautix.com

Marked notes

19

Every published note carries inline Trust Lens markup — category + confidence per claim.

Total graded claims

440

Across all 19 notes; derivable automatically from inline data-trust attributes.

Average confidence

74

Out of 100 — "High" band. Evidence-dense notes reach 83–88; forward-looking notes score 54–55 by design.

Design insight

A low average score is a feature, not a failure — it signals "this note is a position or prediction, not a literature report." The per-artifact table in trust.md makes this auditable for every note.

Why it matters now

AI-assisted science needs legible provenance

LLMs draft more content — provenance blurs without explicit markup

Crawlers and review agents need harvestable claim metadata

schema.org ClaimReview maps directly onto trust.md's model

FAIR assessors can map F/A/I/R sub-keys automatically

The legibility argument

Two files at the root of a repo give any reader — human, crawler, or agent — an immediate, honest answer to: can I reuse this, and how much should I trust it?

Adopt the convention

Two files. Copy, fill, pair.

Step 1 — copy Fork or copy fair.md and trust.md from neuronautix.com/fair.md and neuronautix.com/trust.md

Step 2 — fill honestly partial and planned are features, not failures — the point is a truthful, improvable baseline

Step 3 — pair them Link fair.md → trust.md and back; add companions (CITATION.cff is the cheapest high-value next step)

Step 4 — mark claims Adopt inline epistemic markup so the corpus stats in trust.md are derived, not asserted

Read the full spec: neuronautix.com/notes/2026-06-fair-trust-md-manifests/ · neuronautix.com/contact

Thanks.

Damien Huzard, PhD · Neuronautix · June 2026
neuronautix.com/contact