.xpr — Experiment File Format

The .xpr format is an open, JSON-based standard for documenting biological experiments. It is designed to be human-readable, version-control friendly, and portable across tools, platforms, and institutions.

Inspired by: .ipynb (Jupyter Notebook) — the same cell-based, text-first philosophy, purpose-built for wet and dry lab experiments.

---

Quick example

{
  "xpr": "1.0",
  "metadata": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Effect of temperature on E. coli growth",
    "author": "Dr. Jane Smith",
    "created": "2026-04-11T00:00:00Z",
    "modified": "2026-04-11T00:00:00Z",
    "organism": "Escherichia coli K-12",
    "status": "completed"
  },
  "sections": [
    { "id": "...", "type": "hypothesis", "content": "We hypothesize that E. coli K-12 grows optimally at 37°C." },
    { "id": "...", "type": "protocol", "steps": [{ "step": 1, "description": "Inoculate 10mL LB broth", "duration": "5min" }] },
    { "id": "...", "type": "conclusion", "content": "Optimal growth confirmed at 37°C. Cold stress inhibits growth below 25°C." }
  ]
}

---

Why .xpr?

Most labs store experiments in Word documents, Notion pages, or proprietary ELN software. These formats share a common problem: they are hard to version, hard to diff, hard to search programmatically, and locked to a single platform.

.xpr takes a different approach:

	.xpr	Word / PDF	ELN (proprietary)	Plain Markdown
Plain text, git-diffable	✅	❌	❌	✅
Structured fields (materials, stats, figures)	✅	❌	✅	❌
Platform-agnostic open standard	✅	✅	❌	✅
Programmatically queryable	✅	❌	Partial	❌
Embeds / links raw data files	✅	❌	✅	❌
JSON Schema for validation	✅	❌	❌	❌

The goal is not to replace ELN software — it's to provide a portable, open interchange format that any tool can read and write.

---

Repository contents

Path	Description
spec/xpr-1.0.md	Full format specification
schema/xpr.schema.json	JSON Schema for programmatic validation
viewer/index.html	Self-contained browser viewer (drag and drop any .xpr file)
examples/minimal.xpr	Minimal valid file (3 mandatory sections)
examples/full-example.xpr	All section types and attachment sources
examples/ecoli-temperature.xpr	Realistic filled-out experiment
tools/validate.py	Python validator (uses jsonschema)
tools/validate.js	Node.js validator (uses ajv)
CONTRIBUTING.md	How to propose changes to the spec
CHANGELOG.md	Release history

---

Viewer

Open viewer/index.html in any browser and drag in a .xpr file. No server required, no installation needed.

The viewer renders all section types: hypothesis, materials, protocol steps, observations, figures (Vega-Lite charts), statistical tests, timeline, collaborators, and conclusion.

---

Validate your file

Python:

pip install jsonschema
python tools/validate.py my-experiment.xpr

Node.js:

npm install ajv ajv-formats
node tools/validate.js my-experiment.xpr

---

Section types

Mandatory (every .xpr file must contain these three):

Type	Description
hypothesis	Research question or hypothesis (markdown)
protocol	Experimental steps, with optional source DOI and per-step attachments
conclusion	Summary of findings (markdown)

Optional (zero or more instances, any order):

Type	Description
materials	Reagents and equipment with structured identifiers (RRID, CAS, PubChem, NCBI Taxonomy)
safety	Biosafety level, hazards, waste disposal (markdown)
observation	Raw observations with attachments
analysis	Narrative interpretation of results (markdown)
statistical_analysis	Statistical tests (p-values, sample sizes) with optional attachments
figure	Vega-Lite v5 charts or image attachments, numbered and captioned
timeline	Experiment phases with planned/actual dates and status
collaborators	Team members with roles, ORCIDs, affiliations
note	Free-form notes with optional title

Unknown section types are preserved by compliant parsers — never silently discarded.

---

Implementations

Platform	Type	Link
smarts.bio	Web viewer & editor	view.smarts.bio/experiment
smarts-bio VS Code extension	IDE viewer & editor	VS Code Marketplace
smartsbio JupyterLab extension	Notebook integration	pip install smartsbio-jupyterlab
This repo	Static HTML viewer	viewer/index.html

Building an implementation? Open a PR to add it here.

---

License

• Specification (spec/, schema/): CC0 1.0 Universal — no restrictions, use freely
• Tooling and examples (examples/, tools/, viewer/): Apache 2.0

---

Contributing

See CONTRIBUTING.md for how to propose new section types, new fields, or improvements to the spec.

The spec is intentionally minimal. Extensions should be proposed as new section type values or new optional fields — never as breaking changes.