★★★★ Four-Star Battery Data#

In this notebook, you will learn how to describe a structured battery dataset using ontology-annotated metadata, corresponding to four stars in the Five-Star Battery Data framework.

The goal of star four is to provide explicit metadata that describes:

  • The battery or material under test

  • The test procedure that was carried out

  • The meaning and units of data columns

  • The dataset itself (e.g. title, creator, license)

We do this using controlled vocabularies and semantic formats like JSON-LD.

Watch#

[1]:

import pandas as pd
import json

Step-by-Step Metadata Construction#

To make the process of creating ontology-annotated metadata more understandable, this notebook builds the JSON-LD metadata incrementally, reflecting how real-world metadata often evolves—from minimal structure to rich semantic context.

Step 1: Start with a Skeleton#

We begin by creating a minimal JSON-LD structure with the @context and top-level type (BatteryTest). This gives us a valid but very basic semantic container for describing the battery test.

At this point, both hasTestObject and hasOutput are empty placeholders—we’ll fill them in step-by-step.

[2]:

metadata = {
  "@context": "https://w3id.org/emmo/domain/battery/context",
  "@graph": [
      {
          "@type": "BatteryTest",
          "hasTestObject": {},
          "hasOutput": {}
      }
  ]
}

Step 2: Add Battery Cell Description#

We add a basic description of the test object—a LithiumIonPolymerBattery—by defining:

  • The positive electrode with LithiumCobaltOxide

  • The negative electrode with Graphite

  • The electrolyte as a PolymerElectrolyte

This establishes the core battery structure, using terms from the domain battery ontology.

[3]:

metadata = {
  "@context": "https://w3id.org/emmo/domain/battery/context",
  "@graph": [
      {
          "@type": "BatteryTest",
          "hasTestObject": {
              "@type": "LithiumIonPolymerBattery",
              "hasPositiveElectrode": {
                  "@type": "Electrode",
                  "hasActiveMaterial": {
                      "@type": "LithiumCobaltOxide"
                  }
              },
              "hasNegativeElectrode": {
                  "@type": "Electrode",
                  "hasActiveMaterial": {
                      "@type": "Graphite"
                  }
              },
              "hasElectrolyte": {
                  "@type": "PolymerElectrolyte"
              }
          },
          "hasOutput": {}
      }
  ]
}

Step 3: Add Key Properties#

We enrich the battery description by adding measurable properties:

  • NominalCapacity (e.g. 6500 mAh)

  • NominalVoltage (e.g. 3.8 V)

Each property includes a value (hasNumberValue) and a formal unit from EMMO (e.g. emmo:MilliAmpereHour, emmo:Volt). This ensures both semantic clarity and machine interpretability.

[4]:

metadata = {
  "@context": "https://w3id.org/emmo/domain/battery/context",
  "@graph": [
      {
          "@type": "BatteryTest",
          "hasTestObject": {
              "@type": "LithiumIonPolymerBattery",
              "hasPositiveElectrode": {
                  "@type": "Electrode",
                  "hasActiveMaterial": {
                      "@type": "LithiumCobaltOxide"
                  }
              },
              "hasNegativeElectrode": {
                  "@type": "Electrode",
                  "hasActiveMaterial": {
                      "@type": "Graphite"
                  }
              },
              "hasElectrolyte": {
                  "@type": "PolymerElectrolyte"
              },
              "hasProperty": [
                {
                    "@type": "NominalCapacity",
                    "hasNumericalPart": {
                        "@type": "RealData",
                        "hasNumberValue": 6500
                    },
                    "hasMeasurementUnit": "emmo:MilliAmpereHour"
                },
                {
                    "@type": "NominalVoltage",
                    "hasNumericalPart": {
                        "@type": "RealData",
                        "hasNumberValue": 3.8
                    },
                    "hasMeasurementUnit": "emmo:Volt"
                }
              ]
          },
          "hasOutput": {}
      }
  ]
}

Step 4: Add Test Output Description#

We then define the output of the test using:

  • BatteryTestResult as the output type

  • dcat:Dataset to allow integration with data catalogs

  • A dcat:Distribution block specifying:

    • The media type (application/vnd.apache.parquet)

    • The file URL on Zenodo

    • A link to the csvw:tableSchema that defines column-level meaning

This step connects the metadata to the actual test data, bridging semantics and raw content.

[5]:

metadata = {
  "@context": "https://w3id.org/emmo/domain/battery/context",
  "@graph": [
      {
          "@type": "BatteryTest",
          "hasTestObject": {
              "@type": "LithiumIonPolymerBattery",
              "hasPositiveElectrode": {
                  "@type": "Electrode",
                  "hasActiveMaterial": {
                      "@type": "LithiumCobaltOxide"
                  }
              },
              "hasNegativeElectrode": {
                  "@type": "Electrode",
                  "hasActiveMaterial": {
                      "@type": "Graphite"
                  }
              },
              "hasElectrolyte": {
                  "@type": "PolymerElectrolyte"
              },
              "hasProperty": [
                {
                    "@type": "NominalCapacity",
                    "hasNumericalPart": {
                        "@type": "RealData",
                        "hasNumberValue": 6500
                    },
                    "hasMeasurementUnit": "emmo:MilliAmpereHour"
                },
                {
                    "@type": "NominalVoltage",
                    "hasNumericalPart": {
                        "@type": "RealData",
                        "hasNumberValue": 3.8
                    },
                    "hasMeasurementUnit": "emmo:Volt"
                }
              ]
          },
          "hasOutput": {
                "@type": ["BatteryTestResult", "dcat:Dataset"],
                "dcat:distribution": {
                    "@type": "dcat:Distribution",
                    "dcat:mediaType": "application/vnd.apache.parquet",
                    "dcat:downloadURL": "https://zenodo.org/records/15127867/files/sintef__melasta-slpba842124hv-2024-10-23-15077312__rate-testing.bdf.parquet",
                    "csvw:tableSchema": "https://w3id.org/battery-data-alliance/ontology/battery-data-format/schema"
                }
          }
        }
    ]
}

Step 5: Serialize and Save#

Once the full metadata structure is assembled, we serialize it to a metadata.jsonld file, ready for validation and reuse.

[6]:

# Save to file
with open("metadata.jsonld", "w") as f:
    json.dump(metadata, f, indent=2)

Validate Your JSON-LD#

You can copy-paste the contents of metadata.jsonld into an online validator like:

Check that your metadata resolves correctly and uses well-formed vocabularies.

Why This Matters#

By building up the metadata one layer at a time:

  • You maintain clarity about what each part of the structure represents

  • You learn how to reuse ontology terms consistently

  • You prepare metadata that is valid, discoverable, and linked

This modular approach helps demystify semantic metadata and prepares your dataset for 4-star battery data—and sets the stage for the final star: linked data integration.

Summary#

In this notebook, you learned how to satisfy the requirements for 4-star battery data by creating structured, ontology-annotated metadata in JSON-LD format.

Step

What You Did

Define structure

Created a JSON-LD template with @context and BatteryTest type

Describe the battery

Added a semantic description of the test object using EMMO and BattINFO terms

Add properties

Included battery properties like nominal voltage and capacity with units

Link to dataset output

Connected the test to a data file and schema using dcat and csvw terms

Save metadata

Serialized the complete metadata to a metadata.jsonld file

By following this workflow, your dataset now includes:

  • Machine-readable semantic metadata describing both the battery and the test

  • Ontology-backed terms that promote clarity and interoperability

  • A structured foundation for linked data integration at the 5-star level

This notebook provides a clear and extensible pattern for making battery datasets semantically rich and FAIR-compliant.