Cards & schema

A card is the unit of meaning in Lemma: a typed, schema-validated specification of one scientific principle. Cards live in cards/<domain>/<sub-domain>/<id>.json and every card validates against schema/card.v0.1.json.

A real card

This is a shipping principle card from the corpus, verbatim:

{
  "kind": "principle",
  "id": "density-of-states",
  "version": "1.3.0",
  "name": "Electronic density of states",
  "domain": "physics-condensed-matter",
  "principles": [
    "Bloch theorem",
    "k-point Brillouin-zone sampling",
    "spectral function"
  ],
  "formulaTeX": "g(\\varepsilon) = \\sum_{n,\\mathbf{k}} w_{\\mathbf{k}} \\, \\delta(\\varepsilon - \\varepsilon_{n\\mathbf{k}})",
  "conventions": [
    "g(epsilon) >= 0",
    "spin factor 2 absorbed (non-magnetic)",
    "normalisation: integral from -infinity to epsilon_F of g(epsilon) d epsilon = N_electrons / V"
  ],
  "expectedLimits": [
    "finite at insulator/semiconductor gap edges, zero inside the gap",
    "metallic systems: g(epsilon_F) > 0",
    "smooth under k-mesh refinement (Methfessel-Paxton or Gaussian smearing)",
    "no validation envelope, deliberately: g(epsilon) has no system-independent range. It scales with the cell volume and the number of bands, and its shape depends on the basis, the k-mesh and the smearing width. Any numeric bound would encode one calculation's setup rather than the physics, and would then pass or fail later calculations for reasons unrelated to correctness"
  ],
  "references": [
    "Ashcroft & Mermin, Solid State Physics, ch.8",
    "Martin, Electronic Structure: Basic Theory and Practical Methods, ch.3",
    "Methfessel & Paxton 1989"
  ]
}

(The card also carries a metadata block — authors and review tier — omitted here because it is stripped before the card reaches a model.)

That last expectedLimits entry is worth reading twice. A card is expected to say why it declines to assert a bound, not just to leave the field off. An absent envelope and a deliberate refusal to set one look identical in the JSON otherwise, and they mean very different things to a reviewer.

The fields

A principle card requires kind, id, version, name, principles, formulaTeX, conventions, expectedLimits, and references. domain, validationEnvelopes, crossMethodTolerances, formula, and metadata are optional — see the schema reference.

Field	Meaning
kind	The structural discriminator: principle, ops, hypothesis, or unidentified. The kind is structural, not subject-area.
id	Stable, lowercase, hyphen-separated (^[a-z][a-z0-9-]*$). Part of the URL once published; never reused.
version	Semver. MAJOR for a breaking convention change, MINOR for added limits, PATCH for refs/typos.
name	Human-readable name.
domain	Subject area, hyphenated — e.g. physics-condensed-matter, chemistry-thermodynamics, numerical-methods. Must match the folder path.
principles	The named principles the card rests on.
formulaTeX	The canonical equation in LaTeX (KaTeX-renderable).
conventions	Sign / normalisation / unit conventions the output must follow.
expectedLimits	Asymptotic and boundary cases the output must respect.
references	Primary-source citations (not blog posts).
validationEnvelopes (optional)	Numerical bounds the engine asserts at runtime — an object of { key: [min, max] } tuples in conventional units (e.g. { "gEarth_m_per_s2": [9.79, 9.83] }).
metadata (optional)	Who wrote the card and how far it has been reviewed — authors (at least one, each with a name and optionally orcid / github / role) and a tier of bronze, silver, or gold. See Who wrote a card.

Who wrote a card

A card records its own authorship in an optional metadata block, so credit travels with the JSON rather than living in a git history that repo moves and squashed commits can erase:

"metadata": {
  "authors": [
    { "name": "Ada Lovelace", "orcid": "0000-0000-0000-0000", "role": "curator" }
  ],
  "tier": "silver"
}

tier is the review level the card has reached — bronze, silver, or gold. role is one of author, curator, reviewer, translator, or maintainer.

Metadata never reaches a model. cards_get strips it, so an agent asking for a principle gets the physics and nothing about who wrote it. That is deliberate: a verification substrate should not invite a model to weight a claim by the prestige of its author, and contributor names and ORCIDs should not be shipped to a model provider on every tool call. Metadata is for humans, attribution, and review — read it from the card files or the typed SDK models.

Licensing

The schema is MIT; the cards corpus is CC-BY 4.0. Anyone can read, fork the schema, and contribute a card — attribution is the only requirement, which is what the metadata.authors block above exists to make machine-readable.

One schema, many domains

kind is the structural discriminator — PrincipleCard covers physics, chemistry, biology, climate, mathematics, and engineering because the verification operations are universal. The subject area lives in domain. A card in optics, fluid dynamics, climate, or pure mathematics has the same shape.