Cards schema reference

The canonical wire format for Lemma cards is defined as a single JSON Schema document at schema/card.v0.1.json. This page summarises the shape of every variant; the schema file itself is the authority.

Identifier	Value
$id	https://openlemma.dev/schema/card.v0.1.json
Spec version	JSON Schema 2020-12
Discriminator	top-level kind field
Licence	MIT

A card is a oneOf over four variants — principle, ops, hypothesis, unidentified. Every variant is closed (additionalProperties: false); unknown fields fail validation.

---

PrincipleCard

The structural shape used for physics, chemistry, biology, climate, mathematics, engineering, and numerical methods. The discriminator is structural, not subject-area — the actual domain lives in the domain field.

Field	Type	Required	Notes
kind	const "principle"	yes	Variant discriminator
id	string, kebab-case	yes	Pattern ^[a-z][a-z0-9-]*$. Stable and never reused once published.
version	semver string	yes	MAJOR for breaking convention changes, MINOR for added limits, PATCH for typos / refs.
name	string	yes	Human-readable title.
domain	string	no	Subject area, e.g. "physics-condensed-matter", "chemistry-electrochemistry". Conventional values are listed in the schema.
principles	string array	yes	The underlying physical / mathematical principles in plain English.
formulaTeX	string	yes	Canonical equation in LaTeX. KaTeX-renderable.
conventions	string array	yes	Sign conventions, unit conventions, coordinate frames.
expectedLimits	string array	yes	Plain-English asymptotic / boundary expectations.
references	string array	yes	Canonical sources — textbooks, papers, official documentation.
validationEnvelopes	object	no	Numerical bounds asserted at runtime. Keys are domain-conventional (e.g. gEarth_m_per_s2); values are either [min, max] tuples or richer objects.

---

OpsCard

Parameterised templates for scripting and job-submission tasks (SLURM, Snakemake, Singularity recipes).

Field	Type	Required	Notes
kind	const "ops"	yes	Variant discriminator
id	string, kebab-case	yes	Same pattern as PrincipleCard.id
version	semver string	yes
name	string	yes
description	string	yes	One-paragraph plain-English summary.
parameters	array of OpsParameter	yes	Each entry: { key, label, defaultValue, required, note? }
validation	string array	yes	Validation rules in plain English.
references	string array	yes	Sources.

OpsParameter

Field	Type	Required	Notes
key	string	yes	Identifier used by the template engine.
label	string	yes	Human-readable label.
defaultValue	string	yes	Default; empty string allowed.
required	boolean	yes	Whether the template requires this parameter at instantiation.
note	string	no	Free-form explanation, rendered alongside the label.

---

HypothesisCard

Proposed extensions to the corpus — generated by an LLM, by a human, or by symbolic regression. Explicitly not yet verified; the cross-check engine consumes the declared checks to decide whether the hypothesis can be promoted to a principle.

Field	Type	Required	Notes
kind	const "hypothesis"	yes
id	string, kebab-case	yes
version	semver string	yes
name	string	yes
proposal	string	yes	Plain-English statement of what the hypothesis claims.
proposedFormulaTeX	string	yes	The proposed equation in LaTeX.
derivedFrom	object	no	{ cardId: string, relationship: "extends" | "replaces" | "complements" }
checks	HypothesisChecksSpec	yes	The cross-checks the engine should run.
references	string array	yes
origin	enum	yes	"llm", "human", or "symbolic-regression".
rationale	string	no	Why this hypothesis was proposed.

HypothesisChecksSpec

Field	Type	Notes
dimensional	object	lhsLabel/lhsDims/rhsLabel/rhsDims (canonical DimVecs). Optionally expr (a plain-ASCII RHS expression, e.g. "(1/2)*m*v**2") + symbols (map of symbol → DimVec): when both are present the engine derives the RHS dimensions from the formula and checks them against lhsDims, instead of trusting the declared rhsDims.
limits	array	Each entry: { name, regime, expectedReducesTo }. Currently warn pending symbolic verification.
conservationLaws	array	Each entry: { law, statement }. law is one of energy, momentum, charge, particle-number, total-spin, parity.
referenceCorpus	object	{ mustAgreeWith?: string[], mayContradict?: string[] }. The engine resolves every id against the live corpus.

DimVec

Canonical dimension vector. Each axis is an integer exponent on a primitive dimension. Omitted axes default to zero.

Axis	Meaning	Notes
L	length
T	time
M	mass
E	energy
Q	charge
Theta	temperature	Renders as Greek capital Θ in human output.
N	particle count

---

UnidentifiedCard

Sentinel returned by the IDENTIFY phase when no card honestly matches the request. Surfaced verbatim instead of fabricating a fallback.

Field	Value	Notes
kind	const "unidentified"
id	const "none"
version	const "0.0.0"
name	string
reason	string	Why nothing matched.

---

Validating a card

npx ajv-cli@5 validate --spec=draft2020 \
  -s schema/card.v0.1.json \
  -d "cards/**/*.json"

or in Python:

from artano_lemma import validate_card_payload, parse_card

# Strict validation against the schema:
validate_card_payload(my_card_dict)

# Or validate + parse to a typed model in one call:
card = parse_card(my_card_dict)

See the Python SDK page for the typed models and the validator.