Materials#

How to describe a material: the manufactured product as a material spec, a physical lot or batch as a material instance, both under a curated Level-1 kind.

kind is required and curated: aliases resolve on input (NMC 811, LiFePO4, Si/Gr), an unknown kind is rejected at save.
A kind’s roles list is informative, never restrictive - the role a material plays is stated where it is used.
The spec is the manufactured product (Targray NMC811, grade X); the material instance is one physical lot.
Other records reference a material at whichever level you know - kind key, spec IRI, or lot IRI - and upgrade later without re-modeling.

Define one#

A material spec (the powder as a product)#

Python

from battinfo.api import create_material_spec

record = create_material_spec(
    uid="7d9k-2m4p-8t3x-6nq5",
    name="NMC811 cathode powder",
    kind="nmc811",                     # Level-1 key from the curated vocabulary
    property={
        "specific_capacity": {"value": 200, "unit": "mAh/g"},
        "d50_particle_size": {"value": 10, "unit": "um"},
    },
    source_type="datasheet",
)

Canonical record

{
  "schema_version": "0.2.0",
  "material_spec": {
    "id": "https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5",
    "short_id": "7d9k2m",
    "name": "NMC811 cathode powder",
    "kind": "nmc811",
    "property": {
      "specific_capacity": {
        "value": 200,
        "unit": "mAh/g"
      },
      "d50_particle_size": {
        "value": 10,
        "unit": "um"
      }
    }
  },
  "provenance": {
    "source_type": "datasheet",
    "retrieved_at": 1750000000,
    "battinfo_version": "0.7.0"
  }
}

JSON-LD

Emitted by record_to_jsonld, hosted-context mode.

{
  "@context": [
    "https://w3id.org/emmo/domain/battery/context",
    {
      "schema": "https://schema.org/",
      "dcterms": "http://purl.org/dc/terms/",
      "battinfo": "https://w3id.org/battinfo/"
    }
  ],
  "@type": [
    "Description",
    "schema:ProductModel",
    "schema:CreativeWork"
  ],
  "@id": "https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5",
  "schema:name": "NMC811 cathode powder",
  "schema:sameAs": {
    "@id": "https://w3id.org/emmo/domain/chemical-substance#substance_e877987f_3b08_4e21_8f2e_c280e6bef52f"
  },
  "skos:exactMatch": [
    {
      "@id": "http://www.wikidata.org/entity/Q121086674"
    }
  ],
  "isDescriptionFor": {
    "@type": "LithiumNickelManganeseCobaltOxide811",
    "hasProperty": [
      {
        "@type": [
          "D50ParticleSize",
          "ConventionalProperty"
        ],
        "skos:prefLabel": "D50ParticleSize",
        "hasNumericalPart": {
          "@type": "RealData",
          "hasNumberValue": 10
        },
        "hasMeasurementUnit": "https://w3id.org/emmo#MicroMetre"
      },
      {
        "@type": [
          "SpecificCapacity",
          "ConventionalProperty"
        ],
        "skos:prefLabel": "SpecificCapacity",
        "hasNumericalPart": {
          "@type": "RealData",
          "hasNumberValue": 200
        },
        "schema:unitText": "mAh/g"
      }
    ],
    "@id": "https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5#described",
    "skos:prefLabel": "NMC811 cathode powder"
  }
}

What to notice:

The kind resolves to the chemical-substance class IRI that types the emitted node — the genome’s aggregation axis.

A material instance (one physical lot)#

Python

from battinfo.api import create_material

record = create_material(
    uid="y9xy-kr0v-y5tn-dfj7",
    name="NMC811 lot 2026-04",
    spec_id="https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5",
    source_type="lab",
)

Canonical record

{
  "schema_version": "0.2.0",
  "material": {
    "id": "https://w3id.org/battinfo/material/y9xy-kr0v-y5tn-dfj7",
    "material_spec_id": "https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5",
    "short_id": "y9xykr",
    "name": "NMC811 lot 2026-04"
  },
  "provenance": {
    "source_type": "lab",
    "retrieved_at": 1750000000,
    "battinfo_version": "0.7.0"
  }
}

JSON-LD

Emitted by record_to_jsonld, hosted-context mode.

{
  "@context": [
    "https://w3id.org/emmo/domain/battery/context",
    {
      "schema": "https://schema.org/",
      "dcterms": "http://purl.org/dc/terms/",
      "battinfo": "https://w3id.org/battinfo/"
    }
  ],
  "@id": "https://w3id.org/battinfo/material/y9xy-kr0v-y5tn-dfj7",
  "@type": "schema:ChemicalSubstance",
  "schema:name": "NMC811 lot 2026-04",
  "schema:isVariantOf": {
    "@id": "https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5"
  }
}

What to notice:

material_spec_id links the lot to its product; the lot is what an electrode batch actually consumed.

Fields#

Generated from the packaged JSON Schemas — the same files battinfo validate and the registry’s publish gate enforce. Every record also carries the shared envelope (schema_version, provenance, and optional notes, funding, contributor, license). Quantities are {value, unit} maps and may also carry value_basis (Measured, Conventional, Rated, or Nominal) and conditions (the parameters under which the value holds, each itself a quantity; a qualitative condition may be value_text alone). In JSON-LD, conditions ride a measurement node the quantity isOutputOf; the voltage_reference key instead becomes a hasMetrologicalReference datum on the quantity, beside its unit. When authoring, an instance references its spec with the spec_id= kwarg; the record stores the self-describing <type>_spec_id key shown in the tables below.

material-spec fields#

Schema: material-spec.schema.json · required at top level: schema_version, material_spec, provenance

Field	Type	Required	Description
`id`	→ MaterialSpecIri	yes
`short_id`	→ ShortId
`name`	string	yes	Human-readable material name / grade (e.g. ‘LFP’, ‘Graphite’, ‘NMC811’, ‘PVDF’).
`kind`	string		Required Level-1 MaterialKind key from the curated material_kinds vocabulary (e.g. ‘graphite’, ‘lfp’, ‘nmc811’). The aggregation axis of the Battery Genome; resolves to the kind’s chemical-substance class IRI. An unknown kind is rejected at save time. See battinfo.materials.material_kind_keys().
`grade`	string		Manufacturer grade / product version (e.g. ‘grade X’, ‘v2’). Part of spec identity together with manufacturer and product.
`material_class`	`active_material` \| `binder` \| `conductive_additive` \| `current_collector` … (13 values)		Deprecated in favor of the kind’s roles (the curated vocabulary lists the use-site slots a kind is known to fill): a single forced role is system-relative. Accepted for back-compat and still written by importers; slated for removal at the next record-shape version.
`electrode_polarity`	`positive` \| `negative` \| `none`		Deprecated, do not author: polarity is an electrode property, never a material’s — state it on the electrode or through the cell’s holders. Accepted only so existing records keep validating.
`formula`	string		Chemical formula or idealized composition (e.g. ‘LiFePO4’, ‘C’, ‘Zn’, ‘(C2H2F2)n’).
`chemistry_family`	string		Coarse chemistry family label (e.g. ‘olivine’, ‘layered-oxide’, ‘spinel’, ‘graphitic-carbon’).
`emmo_type`	string		Optional EMMO/domain-battery class label or IRI for this material; informs JSON-LD @type.
`cas_number`	string		CAS Registry Number, when applicable.
`manufacturer`	→ OrgRef		Manufacturer of the item.
`supplier`	→ OrgRef		Supplier or vendor the item was sourced from.
`product_id`	string		Manufacturer / supplier product or grade identifier.
`composition`	→ Composition		Structured derivation of this grade: base material, coatings, dopants, and constituents.
`property`	→ quantitative-properties		Named quantity map of technical properties (snake_case key to value+unit quantity).
`description`	string		Longer free-text description of the material.
`comment`	string		Free-text comment.

material fields#

Schema: material.schema.json · required at top level: schema_version, material, provenance

Field	Type	Required	Description
`id`	→ MaterialIri	yes
`material_spec_id`	→ MaterialSpecIri	yes	IRI of the material-spec this physical lot realizes.
`short_id`	→ ShortId
`name`	string		Human-readable label for this physical lot (e.g. a lab/inventory id).
`lot_id`	string		Manufacturer / supplier lot or batch number.
`batch_id`	string		Internal lab batch identifier, when different from the supplier lot.
`supplier`	→ OrgRef		Supplier or vendor the item was sourced from.
`received_date`	→ FlexDate		Date the lot was received (YYYY, YYYY-MM, or YYYY-MM-DD, or Unix timestamp).
`opened_date`	→ FlexDate		Date this lot was first opened / put into use.
`expires_at`	→ FlexDate		Expiry or retest date for the lot (YYYY, YYYY-MM, or YYYY-MM-DD, or Unix timestamp).
`amount`	→ quantity		Quantity of this lot on hand or consumed (e.g. mass in g, volume in mL).
`storage`	string		Storage conditions for this lot (e.g. ‘argon glovebox’, ‘dry room, -40 degC dew point’).
`processing`	→ Processing
`datasets`	array of → DatasetLink		Characterization datasets for this material lot (XRD, SEM, ICP, PSD, …).
`property`	→ quantitative-properties		Named quantity map of technical properties (snake_case key to value+unit quantity).
`comment`	string		Free-text comment.

Design notes#

The reasoning behind the model

Why three levels. The kind (Level 1) is a curated vocabulary, not a record type — if generic materials were records, the corpus would grow fifty graphites. Level 2 (material-spec) is a manufactured product; Level 3 (material) is a physical lot. This mirrors cells: chemistry/format vocabulary above cell-spec above cell.

The kind’s semantic identity is its chemical-substance ontology class (chemsub), verified per release; the battinfo key is the ergonomic handle. Optional external anchors (wikidata_qid, inchikey, pubchem_cid, mp_id, cas_rn) each emit as a skos:exactMatch link and are populated only where verified — absent means unverified, never guessed. Kinds may carry curated, citable reference_properties (for example a theoretical specific capacity) that the genome compares reported distributions against.

Why roles is a list, and informative only. Roles are system-relative: FEC is both co-solvent and additive, CMC both binder and thickener, and which electrode an active material serves depends on the cell (graphite is the positive electrode of a lithium-counter half cell). So the list means “known to fill these use-site slots”, a use outside it is never an error, and the role a material actually plays is stated where it is used — coating role slots, electrolyte constituent slots, or the component spec that references it. active_material is the one load-bearing role: it gates electrode kinds and anchors reference properties. An empty list is honest too: NMP fills no composition slot (a processing solvent), which its roles_note says.

The embedded ↔ standalone bridge. A material described inline in a composition can be lifted to a standalone spec (material_spec_from_component) and a cell’s inline holders decomposed and de-duplicated (extract_material_specs), so starting embedded never blocks graduating to first-class records.

Two deprecated record fields. electrode_polarity is deprecated and has no authoring path: polarity is an electrode property, never a material’s — the schema accepts the key only so existing records keep validating. material_class is deprecated in favor of the kind’s roles: a single forced role is system-relative, and the kind carries strictly better information; the field stays accepted (importers still write it) until the next record-shape version.

Governance: the vocabulary changes by PR only; tests pin that each kind’s emmo class resolves in the bundled context and names the same substance as its chemsub anchor.

The spec describes; the substance node carries the chemistry. A material spec emits as [Description, schema:ProductModel, schema:CreativeWork] (no MaterialSpecification class is published yet - upstream ask), with the substance node - chemsub class, formula, properties - on the described individual (<spec-IRI>#described) under isDescriptionFor, read the same way as a cell spec’s described battery. The schema:sameAs/skos:exactMatch identity anchors are catalogue facts and ride the spec node itself (skos:exactMatch is symmetric and transitive - on the described substance it would conflate every supplier’s grade through the shared Wikidata IRI). Material lots are physical and keep their typing.