JSON-LD format

Why JSON-LD?

The /api/dpp/{slug}/jsonld endpoint returns DPP data as JSON-LD (JSON for Linked Data). This format provides several advantages over plain JSON:

Semantic interoperability — Every field has a globally unique, dereferenceable identifier. Two systems using the same vocabulary will interpret fields identically without out-of-band coordination.
Graph database compatibility — JSON-LD maps directly to RDF triples and can be loaded into triple stores (Apache Jena, Amazon Neptune, GraphDB) for complex querying.
schema.org tooling — Fields mapped to schema.org terms work with Google's Structured Data Testing Tool, Rich Results Test, and SEO enrichment tools.
EU interoperability requirements — The EU's Ecodesign regulation and Digital Product Passport framework are moving towards semantic data exchange. JSON-LD positions integrations for future regulatory requirements.

The @context

Traceable DPP JSON-LD responses use a dual context:

{
  "@context": {
    "schema": "https://schema.org/",
    "traceable": "https://vocab.traceable.digital/v1#",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  }
}

schema: — schema.org terms for standard product and organisation metadata
traceable: — Traceable's custom vocabulary for battery-specific fields with no schema.org equivalent. The namespace URI https://vocab.traceable.digital/v1# is the canonical identifier for this vocabulary; a machine-readable vocabulary document will be published at that URL at general availability. All traceable: property definitions are documented in the Traceable vocabulary reference section below.
xsd: — XML Schema datatypes for typed literal values (dates, decimals)

@type values

DPP JSON-LD documents use two @type values:

{
  "@type": ["schema:Product", "traceable:BatteryPassport"]
}

schema:Product enables compatibility with general product tooling. traceable:BatteryPassport identifies the document as a Digital Product Passport and activates battery-specific term handling.

The @id and canonical product URI

The @id field identifies the canonical URI for the product — the URL that uniquely and persistently identifies this DPP:

When a GTIN is assigned (GS1-compliant products): the @id is the GS1 Digital Link URI, e.g. https://app.traceable.digital/01/09506000134352/21/SN-2026-00421. This is the URI encoded in the QR code on the physical battery, and it must be the @id for regulatory and semantic web purposes.
When no GTIN is assigned: the @id falls back to the slug-based viewer URL, e.g. https://app.traceable.digital/dpp/swiftvolt-48v-100ah-ev-pack.

Integrations that store or dereference the @id should expect either format. The GS1 Digital Link format is the correct canonical form for EU Battery Regulation compliance.

Full example: EV battery DPP in JSON-LD

{
  "@context": {
    "schema": "https://schema.org/",
    "traceable": "https://vocab.traceable.digital/v1#",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@type": ["schema:Product", "traceable:BatteryPassport"],
  "@id": "https://app.traceable.digital/01/09506000134352/21/SN-2026-00421",
  "schema:name": "SwiftVolt 48V 100Ah EV Pack",
  "schema:identifier": "09506000134352",
  "schema:url": "https://app.traceable.digital/01/09506000134352/21/SN-2026-00421",
  "schema:manufacturer": {
    "@type": "schema:Organization",
    "schema:name": "SwiftVolt Energy Systems GmbH",
    "schema:addressCountry": "DE",
    "schema:vatID": "DE298471625",
    "schema:email": "compliance@swiftvolt.de",
    "schema:address": {
      "@type": "schema:PostalAddress",
      "schema:streetAddress": "Batteriestraße 14",
      "schema:addressLocality": "Munich",
      "schema:postalCode": "80333",
      "schema:addressCountry": "DE"
    }
  },
  "traceable:batteryCategory": "EV_BATTERY",
  "traceable:version": {
    "@type": "xsd:integer",
    "@value": "3"
  },
  "traceable:status": "published",
  "traceable:carbonFootprint": {
    "@type": "traceable:CarbonFootprint",
    "traceable:totalKgCO2ePerKwh": {
      "@type": "xsd:decimal",
      "@value": "61.4"
    },
    "traceable:lifecycleStages": {
      "traceable:rawMaterialExtraction": {
        "@type": "xsd:decimal",
        "@value": "28.2"
      },
      "traceable:manufacturing": {
        "@type": "xsd:decimal",
        "@value": "18.6"
      },
      "traceable:distribution": {
        "@type": "xsd:decimal",
        "@value": "2.1"
      },
      "traceable:usePhase": {
        "@type": "xsd:decimal",
        "@value": "7.3"
      },
      "traceable:endOfLife": {
        "@type": "xsd:decimal",
        "@value": "5.2"
      }
    },
    "traceable:calculationMethodology": "ISO 14067:2018",
    "traceable:verifiedBy": "TÜV Rheinland",
    "traceable:verifiedAt": {
      "@type": "xsd:dateTime",
      "@value": "2025-01-15T00:00:00Z"
    }
  },
  "traceable:recycledContent": {
    "@type": "traceable:RecycledContent",
    "traceable:cobaltPercent": {
      "@type": "xsd:decimal",
      "@value": "16.0"
    },
    "traceable:lithiumPercent": {
      "@type": "xsd:decimal",
      "@value": "6.0"
    },
    "traceable:nickelPercent": {
      "@type": "xsd:decimal",
      "@value": "6.0"
    },
    "traceable:leadPercent": {
      "@type": "xsd:decimal",
      "@value": "0.0"
    }
  },
  "traceable:performance": {
    "@type": "traceable:BatteryPerformance",
    "traceable:nominalCapacityKwh": {
      "@type": "xsd:decimal",
      "@value": "4.8"
    },
    "traceable:ratedVoltageV": {
      "@type": "xsd:integer",
      "@value": "48"
    },
    "traceable:cycleLifeAtEightyPercent": {
      "@type": "xsd:integer",
      "@value": "2000"
    },
    "traceable:roundTripEfficiencyPercent": {
      "@type": "xsd:decimal",
      "@value": "96.2"
    }
  },
  "traceable:compliance": {
    "@type": "traceable:ComplianceDeclaration",
    "traceable:euBatteryRegulation": true,
    "traceable:reachCompliant": true,
    "traceable:rohsCompliant": true,
    "traceable:certifications": ["IEC 62619:2022", "UN 38.3", "CE"]
  },
  "schema:datePublished": {
    "@type": "xsd:dateTime",
    "@value": "2025-02-01T10:14:22Z"
  },
  "schema:dateModified": {
    "@type": "xsd:dateTime",
    "@value": "2025-03-18T08:45:11Z"
  }
}

Parsing JSON-LD in JavaScript

Install the jsonld npm package:

npm install jsonld

Compact the document to simplify property names using your own context:

import jsonld from 'jsonld';

async function compactDppJsonLd(slug) {
  const response = await fetch(
    `https://app.traceable.digital/api/dpp/${slug}/jsonld`
  );
  const document = await response.json();

  // Compact to a simpler local context
  const compacted = await jsonld.compact(document, {
    '@context': {
      name: 'https://schema.org/name',
      manufacturer: 'https://schema.org/manufacturer',
      datePublished: 'https://schema.org/datePublished',
      carbonFootprint: 'https://vocab.traceable.digital/v1#carbonFootprint',
      batteryCategory: 'https://vocab.traceable.digital/v1#batteryCategory',
    }
  });

  return compacted;
}

Frame the document to extract a specific nested structure:

import jsonld from 'jsonld';

async function extractCarbonFootprint(slug) {
  const response = await fetch(
    `https://app.traceable.digital/api/dpp/${slug}/jsonld`
  );
  const document = await response.json();

  const frame = {
    '@context': { 'traceable': 'https://vocab.traceable.digital/v1#' },
    '@type': 'traceable:CarbonFootprint'
  };

  const framed = await jsonld.frame(document, frame);

  // framed['@graph'][0] contains the CarbonFootprint node
  const cf = framed['@graph']?.[0];
  if (!cf) return null;

  return {
    total: cf['traceable:totalKgCO2ePerKwh'],
    verifiedBy: cf['traceable:verifiedBy'],
  };
}

Parsing JSON-LD in Python

Install pyld:

pip install PyLD requests

import requests
from pyld import jsonld


def fetch_and_compact_dpp(slug: str) -> dict:
    response = requests.get(
        f"https://app.traceable.digital/api/dpp/{slug}/jsonld",
        timeout=10
    )
    response.raise_for_status()
    document = response.json()

    context = {
        "@context": {
            "name": "https://schema.org/name",
            "batteryCategory": "https://vocab.traceable.digital/v1#batteryCategory",
            "carbonFootprint": "https://vocab.traceable.digital/v1#carbonFootprint",
        }
    }

    compacted = jsonld.compact(document, context)
    return compacted


def extract_manufacturer_name(slug: str) -> str | None:
    response = requests.get(
        f"https://app.traceable.digital/api/dpp/{slug}/jsonld",
        timeout=10
    )
    response.raise_for_status()
    document = response.json()

    # Frame to extract the Organization node
    frame = {
        "@context": {"schema": "https://schema.org/"},
        "@type": "schema:Organization"
    }
    framed = jsonld.frame(document, frame)
    graph = framed.get("@graph", [])
    if graph:
        return graph[0].get("schema:name")
    return None

Plain JSON extraction (without a JSON-LD library)

For systems that do not need full JSON-LD processing, you can treat the response as plain JSON and navigate to known fields directly:

async function extractKeyFields(slug) {
  const response = await fetch(
    `https://app.traceable.digital/api/dpp/${slug}/jsonld`
  );
  const doc = await response.json();

  // Navigate to known paths directly — no library needed
  return {
    productName: doc['schema:name'],
    batteryCategory: doc['traceable:batteryCategory'],
    manufacturerName: doc['schema:manufacturer']?.['schema:name'],
    carbonFootprintTotal: doc['traceable:carbonFootprint']?.['traceable:totalKgCO2ePerKwh'],
    publishedAt: doc['schema:datePublished']?.['@value'],
  };
}

This approach is simple but brittle — it breaks if the Traceable context is updated to use prefixes differently. Use a JSON-LD library for production integrations.

Embedding in HTML head for search engines

Paste the JSON-LD response directly into a <script> tag in your HTML <head>:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>SwiftVolt 48V 100Ah EV Pack — Battery Passport</title>

  <!-- Traceable DPP JSON-LD — structured data for search engines -->
  <script type="application/ld+json">
  {
    "@context": {
      "schema": "https://schema.org/",
      "traceable": "https://vocab.traceable.digital/v1#"
    },
    "@type": ["schema:Product", "traceable:BatteryPassport"],
    "@id": "https://app.traceable.digital/01/09506000134352/21/SN-2026-00421",
    "schema:name": "SwiftVolt 48V 100Ah EV Pack",
    "schema:manufacturer": {
      "@type": "schema:Organization",
      "schema:name": "SwiftVolt Energy Systems GmbH"
    }
  }
  </script>
</head>
<body>
  <!-- page content -->
</body>
</html>

The Traceable public DPP viewer at https://app.traceable.digital/dpp/{slug} automatically embeds the JSON-LD in its HTML <head>, so all published DPPs are already discoverable by search engines without any additional work.

Validating with Google's tools

To validate your JSON-LD markup:

Go to search.google.com/test/rich-results
Enter the URL of your product page or paste the JSON-LD directly
The tool will highlight any warnings or errors in the structured data

Note: Google primarily validates schema.org terms. traceable: terms will not be recognised by Google's tool but will not cause errors.

Traceable vocabulary reference

The following table defines all traceable: terms used in DPP JSON-LD responses. The full URI for each term is https://vocab.traceable.digital/v1#{term}.

Term	Type	Description
`traceable:BatteryPassport`	Class	The type assigned to all DPP JSON-LD documents. Identifies the document as a Digital Product Passport under EU Battery Regulation 2023/1542.
`traceable:batteryCategory`	Property	Battery classification. One of: `EV_BATTERY`, `LMT_BATTERY`, `INDUSTRIAL_BATTERY`, `SLI_BATTERY`, `PORTABLE_BATTERY`.
`traceable:version`	Property	Integer version number of the DPP, incremented each time the product is updated and republished.
`traceable:status`	Property	Publication status. `"published"` for all DPPs returned by the public API.
`traceable:slug`	Property	The URL-safe product identifier used in JSON API paths (e.g. `/api/dpp/{slug}`).
`traceable:carbonFootprint`	Property	Object containing the battery's lifecycle carbon footprint data.
`traceable:CarbonFootprint`	Class	The type of the carbon footprint object.
`traceable:totalKgCO2ePerKwh`	Property	Total lifecycle carbon footprint in kg CO₂e per kWh of rated energy.
`traceable:lifecycleStages`	Property	Object containing carbon footprint breakdown by lifecycle stage.
`traceable:rawMaterialExtraction`	Property	Carbon footprint contribution from raw material extraction (kg CO₂e/kWh).
`traceable:manufacturing`	Property	Carbon footprint contribution from cell and battery manufacturing (kg CO₂e/kWh).
`traceable:distribution`	Property	Carbon footprint contribution from transport and logistics (kg CO₂e/kWh).
`traceable:usePhase`	Property	Carbon footprint contribution from operational energy consumption (kg CO₂e/kWh).
`traceable:endOfLife`	Property	Carbon footprint contribution from end-of-life processing (kg CO₂e/kWh).
`traceable:verifiedBy`	Property	Name of the third-party verifier who audited the carbon footprint declaration. Null if self-declared.
`traceable:verifiedAt`	Property	ISO 8601 date of third-party verification. Null if not yet verified.
`traceable:recycledContent`	Property	Object containing recycled material percentages for regulated materials.
`traceable:cobaltPercent`	Property	Percentage of cobalt derived from recycled sources (0–100).
`traceable:lithiumPercent`	Property	Percentage of lithium derived from recycled sources (0–100).
`traceable:nickelPercent`	Property	Percentage of nickel derived from recycled sources (0–100).
`traceable:leadPercent`	Property	Percentage of lead derived from recycled sources (0–100).
`traceable:performance`	Property	Object containing electrical performance and durability metrics.
`traceable:nominalCapacityKwh`	Property	Rated energy capacity in kWh.
`traceable:ratedVoltageV`	Property	Nominal operating voltage in volts.
`traceable:cycleLifeAtEightyPercent`	Property	Number of full charge/discharge cycles to 80% of original capacity.
`traceable:roundTripEfficiencyPercent`	Property	Round-trip energy efficiency as a percentage. May be null for some battery categories.
`traceable:operatingTempMinC`	Property	Minimum rated operating temperature in °C.
`traceable:operatingTempMaxC`	Property	Maximum rated operating temperature in °C.
`traceable:hazardousSubstances`	Property	Array of hazardous substance objects for substances present above 0.1% by weight.
`traceable:HazardousSubstance`	Class	The type of each item in the `hazardousSubstances` array.
`traceable:casNumber`	Property	Chemical Abstracts Service (CAS) registry number for the substance.
`traceable:concentrationPercent`	Property	Concentration of the substance as a percentage of total battery mass.
`traceable:supplyChain`	Property	Object containing supply chain due diligence summary information.
`traceable:dueDiligencePolicyUrl`	Property	URL of the operator's published supply chain due diligence policy. Null if not provided.
`traceable:compliance`	Property	Object containing regulatory compliance declarations.
`traceable:euBatteryRegulation`	Property	Boolean. `true` if the product is declared compliant with EU Battery Regulation 2023/1542.
`traceable:reachCompliant`	Property	Boolean. `true` if REACH compliance is declared.
`traceable:rohsCompliant`	Property	Boolean. `true` if RoHS compliance is declared.
`traceable:certifications`	Property	Array of strings listing certification standards met (e.g. `"IEC 62619:2022"`).

Why JSON-LD?​

The @context​

@type values​

The @id and canonical product URI​

Full example: EV battery DPP in JSON-LD​

Parsing JSON-LD in JavaScript​

Parsing JSON-LD in Python​

Plain JSON extraction (without a JSON-LD library)​

Embedding in HTML head for search engines​

Validating with Google's tools​

Traceable vocabulary reference​