Datasets#

How to describe measured data: a dataset record per data artifact, and a dataset series (collection) record for the deposit or study they belong to.

  • A dataset describes data files (URLs, checksums, measured variables); the files stay where they are published.

  • about links the cell and the test the data came from.

  • A series is an ordinary dataset flavored additional_type: ["DatasetSeries"]; members point at it with series_id, so the collection publishes first.

Define one#

A member dataset#

from battinfo import Cell, CellSpec, Dataset, Test

cell = Cell(
    id="https://w3id.org/battinfo/cell/y9xy-kr0v-y5tn-dfj7",
    cell_spec=CellSpec(
        id="https://w3id.org/battinfo/spec/7d9k-2m4p-8t3x-6nq5",
        manufacturer="Samsung SDI", model="INR21700-50E",
        format="cylindrical", chemistry="Li-ion",
    ),
    serial_number="LAB-2026-0001",
)
test = Test(
    id="https://w3id.org/battinfo/test/3w87-0ddf-ryjg-evxe",
    cell=cell, kind="cycling", status="completed",
)
dataset = Dataset(
    id="https://w3id.org/battinfo/dataset/6nec-h262-tthy-4rnt",
    name="INR21700-50E cycle-life dataset",
    description="Cycle-life time series for cell LAB-2026-0001.",
    cell=cell,
    test=test,
    license="https://creativecommons.org/licenses/by/4.0/",
    access_url="https://doi.org/10.5281/zenodo.1234567",
    download_url="https://zenodo.org/records/1234567/files/run.parquet",
    data_format="application/x-parquet",
    checksum_algorithm="md5",
    checksum_value="9e107d9d372bb6826bd81d3542a419d6",
    # Membership in a dataset series (a collection record): emitted as
    # dcat:inSeries and schema:isPartOf. The collection publishes first.
    series_id="https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd",
    source={"type": "measurement", "retrieved_at": 1750000000},
)
record = dataset.to_record()

{
  "schema_version": "0.2.0",
  "dataset": {
    "id": "https://w3id.org/battinfo/dataset/6nec-h262-tthy-4rnt",
    "short_id": "6nech2",
    "identifier": "dataset:6nec-h262-tthy-4rnt",
    "name": "INR21700-50E cycle-life dataset",
    "description": "Cycle-life time series for cell LAB-2026-0001.",
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "access_url": "https://doi.org/10.5281/zenodo.1234567",
    "about": [
      "https://w3id.org/battinfo/cell/y9xy-kr0v-y5tn-dfj7",
      "https://w3id.org/battinfo/test/3w87-0ddf-ryjg-evxe"
    ],
    "series_id": "https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd",
    "distributions": [
      {
        "type": "DataDownload",
        "content_url": "https://zenodo.org/records/1234567/files/run.parquet",
        "encoding_format": "application/x-parquet",
        "checksum": {
          "algorithm": "md5",
          "value": "9e107d9d372bb6826bd81d3542a419d6"
        }
      }
    ]
  },
  "provenance": {
    "source_type": "measurement",
    "retrieved_at": 1750000000,
    "battinfo_version": "0.7.0"
  }
}

Emitted by record_to_jsonld, hosted-context mode.

{
  "@context": "https://w3id.org/battinfo/context/records/v1.json",
  "@type": "http://www.w3.org/ns/dcat#Dataset",
  "@id": "https://w3id.org/battinfo/dataset/6nec-h262-tthy-4rnt",
  "dcterms:title": "INR21700-50E cycle-life dataset",
  "dcat:inSeries": {
    "@id": "https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd"
  },
  "schema:isPartOf": {
    "@id": "https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd"
  },
  "dcterms:description": "Cycle-life time series for cell LAB-2026-0001.",
  "schema:description": "Cycle-life time series for cell LAB-2026-0001.",
  "dcterms:license": {
    "@id": "https://creativecommons.org/licenses/by/4.0/"
  },
  "dcat:accessURL": {
    "@id": "https://doi.org/10.5281/zenodo.1234567"
  },
  "dcterms:subject": [
    {
      "@id": "https://w3id.org/battinfo/cell/y9xy-kr0v-y5tn-dfj7"
    },
    {
      "@id": "https://w3id.org/battinfo/test/3w87-0ddf-ryjg-evxe"
    }
  ],
  "dcat:distribution": [
    {
      "@type": "dcat:Distribution",
      "dcat:downloadURL": {
        "@id": "https://zenodo.org/records/1234567/files/run.parquet"
      },
      "dcat:mediaType": "application/x-parquet",
      "spdx:checksum": {
        "@type": "spdx:Checksum",
        "spdx:checksumAlgorithm": {
          "@id": "spdx:checksumAlgorithm_md5"
        },
        "spdx:checksumValue": "9e107d9d372bb6826bd81d3542a419d6"
      }
    }
  ],
  "dcterms:source": {
    "@type": "prov:Entity",
    "dcterms:type": "measurement",
    "prov:generatedAtTime": "2025-06-15T15:06:40+00:00"
  }
}

What to notice:

  • series_id emits BOTH dcat:inSeries (the DCAT 3 membership edge) and schema:isPartOf (what dataset search engines read).

  • about links the cell and the test; the distribution carries the download URL and checksum.

The collection (dataset series)#

from battinfo import Dataset

collection = Dataset(
    id="https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd",
    name="INR21700-50E cycle-life collection",
    description="All cycle-life datasets of the 2026 INR21700-50E study.",
    # The series flavor: an ordinary dataset record, typed
    # dcat:DatasetSeries by this marker — no separate record type.
    additional_type=["DatasetSeries"],
    # The collection IS the deposit, so the deposit DOI is its own
    # external identifier.
    identifier={"property_id": "doi", "value": "10.5281/zenodo.1234567"},
    license="https://creativecommons.org/licenses/by/4.0/",
    access_url="https://doi.org/10.5281/zenodo.1234567",
    # No cell, test, or distributions: the member datasets carry those.
    source={"type": "catalog", "retrieved_at": 1750000000},
)
record = collection.to_record()

{
  "schema_version": "0.2.0",
  "dataset": {
    "id": "https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd",
    "short_id": "0rp6kn",
    "identifier": {
      "property_id": "doi",
      "value": "10.5281/zenodo.1234567"
    },
    "name": "INR21700-50E cycle-life collection",
    "description": "All cycle-life datasets of the 2026 INR21700-50E study.",
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "additional_type": [
      "DatasetSeries"
    ],
    "access_url": "https://doi.org/10.5281/zenodo.1234567"
  },
  "provenance": {
    "source_type": "catalog",
    "retrieved_at": 1750000000,
    "battinfo_version": "0.7.0"
  }
}

Emitted by record_to_jsonld, hosted-context mode.

{
  "@context": "https://w3id.org/battinfo/context/records/v1.json",
  "@type": [
    "http://www.w3.org/ns/dcat#Dataset",
    "http://www.w3.org/ns/dcat#DatasetSeries"
  ],
  "@id": "https://w3id.org/battinfo/dataset/0rp6-kncv-cyem-qwcd",
  "dcterms:title": "INR21700-50E cycle-life collection",
  "dcterms:description": "All cycle-life datasets of the 2026 INR21700-50E study.",
  "schema:description": "All cycle-life datasets of the 2026 INR21700-50E study.",
  "dcterms:license": {
    "@id": "https://creativecommons.org/licenses/by/4.0/"
  },
  "dcat:accessURL": {
    "@id": "https://doi.org/10.5281/zenodo.1234567"
  },
  "dcterms:source": {
    "@type": "prov:Entity",
    "dcterms:type": "catalog",
    "prov:generatedAtTime": "2025-06-15T15:06:40+00:00"
  }
}

What to notice:

  • @type carries dcat:DatasetSeries alongside dcat:Dataset — no new record type exists.

  • No about and no distributions: the members hold the cell links and the files, and the strict policy admits that for the series flavor only.

Common examples#

A selection of real, validated records from the packaged examples corpus — each one click away, included from its single source under examples/. The full, living library is the registry: browse it there.

NMC811 coin cell cycling data (dataset)

The record ships in the installed wheel — load it as a starting point:

import json
from importlib import resources

record = json.loads(
    resources.files("battinfo")
    .joinpath("data/examples/dataset/dataset-nns1-gh5p-v5n1-td17.json")
    .read_text(encoding="utf-8")
)

{
  "schema_version": "0.2.0",
  "dataset": {
    "id": "https://w3id.org/battinfo/dataset/nns1-gh5p-v5n1-td17",
    "short_id": "nns1gh",
    "identifier": "dataset:nns1-gh5p-v5n1-td17",
    "name": "NMC811 coin cell cycling data",
    "access_url": "https://example.org/dataset/nns1-gh5p-v5n1-td17",
    "description": "Raw galvanostatic cycling export for one NMC811-Graphite coin cell.",
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "measurement_techniques": [
      "cycling"
    ],
    "measurement_methods": [
      "galvanostatic cycling"
    ],
    "variable_measured": [
      {
        "name": "voltage",
        "unit_text": "V"
      },
      {
        "name": "current",
        "unit_text": "A"
      },
      {
        "name": "capacity",
        "unit_text": "Ah"
      }
    ],
    "about": [
      "https://w3id.org/battinfo/cell/ag7d-b4fp-r0sv-226m",
      "https://w3id.org/battinfo/test/ezwb-tj8t-0474-7dgh"
    ],
    "created_at": 1781772876,
    "modified_at": 1781772876,
    "published_at": 1781772876
  },
  "provenance": {
    "source_type": "measurement",
    "retrieved_at": 1781772876
  }
}

Emitted by record_to_jsonld, hosted-context mode.

{
  "@context": "https://w3id.org/battinfo/context/records/v1.json",
  "@type": "http://www.w3.org/ns/dcat#Dataset",
  "@id": "https://w3id.org/battinfo/dataset/nns1-gh5p-v5n1-td17",
  "dcterms:title": "NMC811 coin cell cycling data",
  "dcterms:description": "Raw galvanostatic cycling export for one NMC811-Graphite coin cell.",
  "schema:description": "Raw galvanostatic cycling export for one NMC811-Graphite coin cell.",
  "dcterms:license": {
    "@id": "https://creativecommons.org/licenses/by/4.0/"
  },
  "dcat:accessURL": {
    "@id": "https://example.org/dataset/nns1-gh5p-v5n1-td17"
  },
  "dcterms:created": "2026-06-18T08:54:36Z",
  "dcterms:modified": "2026-06-18T08:54:36Z",
  "dcterms:issued": "2026-06-18T08:54:36Z",
  "schema:datePublished": "2026-06-18T08:54:36Z",
  "schema:measurementTechnique": [
    "cycling"
  ],
  "schema:measurementMethod": [
    "galvanostatic cycling"
  ],
  "schema:variableMeasured": [
    {
      "@type": "schema:PropertyValue",
      "schema:name": "voltage",
      "schema:unitText": "V"
    },
    {
      "@type": "schema:PropertyValue",
      "schema:name": "current",
      "schema:unitText": "A"
    },
    {
      "@type": "schema:PropertyValue",
      "schema:name": "capacity",
      "schema:unitText": "Ah"
    }
  ],
  "dcterms:subject": [
    {
      "@id": "https://w3id.org/battinfo/cell/ag7d-b4fp-r0sv-226m"
    },
    {
      "@id": "https://w3id.org/battinfo/test/ezwb-tj8t-0474-7dgh"
    }
  ],
  "dcterms:source": {
    "@type": "prov:Entity",
    "dcterms:type": "measurement",
    "prov:generatedAtTime": "2026-06-18T08:54:36+00:00"
  }
}
NMC811 powder XRD pattern (dataset)

The record ships in the installed wheel — load it as a starting point:

import json
from importlib import resources

record = json.loads(
    resources.files("battinfo")
    .joinpath("data/examples/dataset/dataset-nxv4-ecrt-9wnm-a2yt.json")
    .read_text(encoding="utf-8")
)

{
  "schema_version": "0.2.0",
  "dataset": {
    "id": "https://w3id.org/battinfo/dataset/nxv4-ecrt-9wnm-a2yt",
    "short_id": "nxv4ec",
    "identifier": "dataset:nxv4-ecrt-9wnm-a2yt",
    "name": "NMC811 powder XRD pattern",
    "access_url": "https://example.org/dataset/nxv4-ecrt-9wnm-a2yt",
    "description": "X-ray diffraction pattern of an NMC811 cathode powder lot.",
    "license": "https://creativecommons.org/licenses/by/4.0/",
    "measurement_techniques": [
      "X-ray diffraction"
    ],
    "variable_measured": [
      {
        "name": "two_theta",
        "unit_text": "deg"
      },
      {
        "name": "intensity",
        "unit_text": "counts"
      }
    ],
    "created_at": 1781778468,
    "modified_at": 1781778468,
    "published_at": 1781778468
  },
  "provenance": {
    "source_type": "measurement",
    "retrieved_at": 1781778468
  }
}

Emitted by record_to_jsonld, hosted-context mode.

{
  "@context": "https://w3id.org/battinfo/context/records/v1.json",
  "@type": "http://www.w3.org/ns/dcat#Dataset",
  "@id": "https://w3id.org/battinfo/dataset/nxv4-ecrt-9wnm-a2yt",
  "dcterms:title": "NMC811 powder XRD pattern",
  "dcterms:description": "X-ray diffraction pattern of an NMC811 cathode powder lot.",
  "schema:description": "X-ray diffraction pattern of an NMC811 cathode powder lot.",
  "dcterms:license": {
    "@id": "https://creativecommons.org/licenses/by/4.0/"
  },
  "dcat:accessURL": {
    "@id": "https://example.org/dataset/nxv4-ecrt-9wnm-a2yt"
  },
  "dcterms:created": "2026-06-18T10:27:48Z",
  "dcterms:modified": "2026-06-18T10:27:48Z",
  "dcterms:issued": "2026-06-18T10:27:48Z",
  "schema:datePublished": "2026-06-18T10:27:48Z",
  "schema:measurementTechnique": [
    "X-ray diffraction"
  ],
  "schema:variableMeasured": [
    {
      "@type": "schema:PropertyValue",
      "schema:name": "two_theta",
      "schema:unitText": "deg"
    },
    {
      "@type": "schema:PropertyValue",
      "schema:name": "intensity",
      "schema:unitText": "counts"
    }
  ],
  "dcterms:source": {
    "@type": "prov:Entity",
    "dcterms:type": "measurement",
    "prov:generatedAtTime": "2026-06-18T10:27:48+00:00"
  }
}

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.

dataset fields#

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

Field

Type

Required

Description

id

→ DatasetIri

yes

Canonical IRI of this dataset record.

short_id

→ ShortId

identifier

→ Identifier

yes

Identifier(s) for the dataset (e.g. DOI, accession number), as strings or PropertyValue pairs.

name

string

yes

Dataset title.

description

string

Free-text description of the dataset.

access_url

string

yes

Landing page or direct access URL for the dataset.

same_as

array of string

Other IRIs identifying the same dataset (e.g. a Zenodo DOI URL).

about

array of → AboutRef

What the dataset is about: canonical cell or test IRIs, or external URIs. Source of truth for what a dataset describes; the cell-instance datasets list and test.dataset_ids are back-references derived from it.

additional_type

string or array of string

Extra JSON-LD type IRIs or labels stacked onto the record’s @type.

license

string

License IRI or SPDX identifier governing reuse.

version

string

Dataset version label.

keywords

array of string

Free-text keywords for discovery.

creators

array of → PersonOrOrganization

People and/or organizations that created the data.

publisher

→ Organization

Organization that published the dataset.

funders

array of → PersonOrOrganization

Parties that funded creation of the dataset.

citations

array of → Citation

Related works to cite alongside the dataset (papers, source datasets, software).

measurement_techniques

array of string

Measurement techniques used, as labels or ontology IRIs.

measurement_methods

array of string

Measurement methods used, as labels or ontology IRIs.

variable_measured

array of → VariableMeasured

Variables (columns or signals) recorded in the dataset.

is_accessible_for_free

boolean

Whether access is free of charge.

conditions_of_access

string

Human-readable access conditions (e.g. ‘registration required’).

in_language

string

Language of the dataset metadata (BCP 47 tag).

created_at

→ UnixTime

Unix timestamp when the dataset was created.

modified_at

→ UnixTime

Unix timestamp when the dataset was last modified.

published_at

→ UnixTime

Unix timestamp when the dataset was published.

temporal_coverage

string

Time period the data covers (ISO 8601 interval).

spatial_coverage

string

Geographic area the data covers.

distributions

array of → DataDistribution

Downloadable files that make up the dataset.

main_entity

→ CsvwMainEntity or array of → CsvwMainEntity

CSVW table description(s) documenting the tabular structure of the data files (the data dictionary).

is_based_on

array of string

URIs of resources this dataset is derived from.

series_id

→ DatasetIri

included_in_data_catalog

string or → DataCatalog

Catalog(s) the dataset is listed in (e.g. the Battery Genome registry).

Design notes#

The reasoning behind the model

The record is the semantic layer over the files. Distributions carry the download URL, media type, byte size, and checksum verbatim from where the data is published; variable_measured and the measurement technique say what is inside without moving it.

Self-reference has exactly three honest slots. A dataset’s own archive DOI belongs in access_url (where the file lives), same_as (the archived representation of this same dataset), and a citation typed kind: "dataset" (how the registry derives the DOI) — never in a plain provenance citation, which means “a paper this record supports” and would make the dataset cite itself as its own literature.

Why the series is a flavor, not a type. DCAT 3 declares dcat:DatasetSeries a subclass of dcat:Dataset, so the collection is an ordinary dataset record flavored by additional_type, and membership is one edge: the member’s series_id, emitted as both dcat:inSeries and schema:isPartOf. Members carry the forward link, so the collection publishes first. A series record needs no cell link of its own — its members hold them — and the strict policy admits that for the series flavor only.