The semantic data layer for battery technology

Create, validate, and publish battery metadata as machine-readable Linked Data —
typed against EMMO domain-battery
and resolvable through persistent https://w3id.org/battinfo/ identifiers.

Quickstart ·
Documentation ·
How-to guides ·
Tutorials ·
Contributing ·
Cite

New words? The plain-language glossary decodes
Linked Data, EMMO, IRI, and friends in two sentences each.

BattINFO provides a Python library, a CLI, and a canonical asset suite — JSON
Schemas, ontology mappings, profiles, and examples — that make it straightforward
to describe batteries as valid, machine-readable Linked Data.

Every record published through BattINFO is a valid RDF document, typed against
EMMO domain-battery and resolvable through persistent https://w3id.org/battinfo/
IRIs. The result is battery metadata that is interoperable by construction,
queryable with SPARQL, and Battery Pass-compatible out of the box.

Table of contents

• Why BattINFO
• Installation
• Quickstart
• Tutorials
• What BattINFO does
• Semantic foundation
• Project status
• Repository layout
• Core principles
• Contributing
• Citation
• License

Why BattINFO

Battery data is fragmented across spreadsheets, vendor datasheets, and ad-hoc
JSON. BattINFO turns that into a single, semantically-grounded record model:

• Write plain JSON or Python — get validated, EMMO-aligned JSON-LD.
• Interoperable by construction — records share one ontology, one context, and one identifier scheme.
• Provenance built in — a CellSpec → Cell → Test → Dataset chain links every measurement back to the cell that produced it.
• Standards-ready — Battery Pass-compatible output, pinned per release.

Installation

Requires Python 3.11+.

BattINFO is not on PyPI until the 0.8 release. Until then, install from source
into a virtual environment:

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install "git+https://github.com/BIG-MAP/BattINFO.git"

Optional extras: battinfo[processing] (cycler-file conversion via ws.convert()

• plotting), battinfo[tabular] (CSV/Parquet/XLSX readers), battinfo[publish]
  (RO-Crate validation), battinfo[storage] (S3), battinfo[docs] (Sphinx), and
  battinfo[dev] (full test/lint/build toolchain). The processing extra also needs
  batterydf, which is not yet on PyPI. Until it ships, pip install "battinfo[processing]"
  cannot resolve; install the processing dependencies directly instead:

pip install "git+https://github.com/battery-data-alliance/battery-data-format.git" matplotlib plotly

Developing on BattINFO? This repo uses uv:

uv sync --all-extras   # creates .venv and installs from uv.lock

Quickstart

from battinfo import CellSpec, publish

result = publish(
    CellSpec(
        manufacturer="Panasonic",
        model="NCR18650B",
        format="cylindrical",
        chemistry="Li-ion",
        nominal_capacity={"value": 3.4, "unit": "Ah"},
    ),
    destination="local",
    root=".battinfo/my-library",
)
print(result.canonical_iri)
# https://w3id.org/battinfo/spec/xxxx-xxxx-xxxx-xxxx

That IRI is permanent, but not yet resolvable on the web — opening it in a
browser returns 404 for a record published locally. A local publish mints the
identity; it becomes dereferenceable once you publish the record to the
registry (ws.publish(), see Tutorial 6).

destination="local" writes to a .battinfo/ directory (a dot-directory —
ls -a to see it):

.battinfo/my-library/
├── index.json
└── examples/cell-spec/cell-spec-<id>.json   # the canonical record JSON

Or from the command line:

battinfo --help

For interactive, multi-record work — cells, tests, datasets, equipment — the
authoring workspace is the blessed surface:

import battinfo
ws = battinfo.workspace(".")
ws.quickstart()   # prints a copy-pasteable end-to-end example

Lab work? Start at the how-to guides — twelve bench
tasks (register materials, build a cell from components, label cells, convert
cycler exports, publish) each mapped to a runnable recipe. The
capability table
shows which surface (workspace, battinfo.api, CLI) authors which record types today.

→ Read the full quickstart and the documentation index.

Tutorials

Six tutorial notebooks in docs/guides/ — one story, from the
record model to a published dataset. Each runs from its own folder and writes
only to a throwaway _scratch/ directory next to it.

What BattINFO does

• Validates battery metadata as plain JSON (JSON Schema / Pydantic) and as semantic RDF (JSON-LD + URDNA2015 normalisation).
• Maps JSON inputs into domain-battery-aligned JSON-LD using authoritative curated property and unit mappings.
• Produces Battery Pass-compatible JSON-LD (pinned to v1.2.0).
• Provides profiles, examples, and mapping rules for all common battery record types.
• Supports a reusable cell-spec library, curated once as BattINFO descriptors and published as generated RDF/JSON-LD.
• Publishes dataset metadata with a core CellSpec → Cell → Test → Dataset provenance chain.

Semantic foundation

Published records use:

• hasProperty → [ClassName, ConventionalProperty] → hasNumericalPart → hasNumericalValue (canonical EMMO quantity pattern)
• hasMeasurementUnit → full EMMO or QUDT IRI (never a bare string)
• @type stacking: a cylindrical LFP cell is simultaneously BatteryCell, CylindricalBattery, LithiumIonBattery, LithiumIronPhosphateBattery, and LithiumIonGraphiteBattery

Project status

Beta. 1,175 tests pass across Python 3.11 and 3.12 on Linux
and Windows. Ontology dependency versions are pinned and verified.
See docs/scope.md for the full capability map.

Supported

• Cell-descriptor validation and mapping, canonical record query/save/publish/index flows, JSON-LD-first publication, and validation policies.
• CLI and Python API covering cell-spec, cell-instance, test, dataset, and test-protocol records.

Preview (may still change)

• Reusable cell-spec library flows beyond the walkthrough fixtures.

In development (no stability promise)

• Registry sync/query (battinfo push, battinfo registry).
• Large-scale reference validation.

Run the verification gate locally:

.venv\Scripts\python .tools/quality/run_verification.py

Repository layout

Core principles

• Domain-battery is the normative ontology (semantics and terms). BattINFO is non-normative and operational (schemas, mappings, tooling).
• The canonical contract is JSON Schema; Pydantic models are generated for the CLI and Python API.
• JSON-LD-first publication: every record rendered for the resolver or registry is valid RDF aligned to domain-battery.
• Stable, opaque identifiers: all published entities carry a https://w3id.org/battinfo/{type}/{uid} IRI, governed by IDENTIFIER_POLICY.md.
• Battery Pass JSON-LD outputs are supported and pinned per release.
• BattINFO does not host or modify the domain-battery ontology.

Contributing

Contributions are welcome. Please open an issue to discuss substantial changes
before submitting a pull request, and make sure the full quality gate passes:

uv sync --all-extras
uv run ruff check src tests
uv run mypy
uv run pytest -q tests

CI runs the same checks across Python 3.11/3.12 on Linux and Windows via the
CI workflow, alongside
Security (pip-audit + CodeQL) and
Docs builds.

Citation

If you use BattINFO in your research, please cite it. The concept DOI arrives
with the 0.8 release (the first Zenodo-archived release); the badge above will
then resolve to a citable record:

@software{battinfo,
  title        = {BattINFO: The semantic data layer for battery technology},
  author       = {Clark, Simon and Friis, Jesper and L{\o}nstad Bleken, Francesca and Flores, Eibar and Stier, Simon and Battaglia, Corsin},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.XXXXXXX},
  url          = {https://github.com/BIG-MAP/BattINFO}
}

Maintainers: mint a Zenodo concept DOI on the first tagged release and
replace zenodo.XXXXXXX (in the badge and the citation above) with the real
identifier.

License

Distributed under the Apache License 2.0. See LICENSE.

Acknowledgements

Built on the EMMO ontology suite — in particular
domain-battery and
domain-electrochemistry — and aligned with the
Battery Pass data content guidance.