JSON-LD für Digitale Produktpässe (und wo EPCIS 2.0 hineinpasst)

Ein Digitaler Produktpass soll von Menschen und von Maschinen gelesen werden: dem Wareneingangssystem eines Recyclers, einer Zoll-API, einem Marktplatz-Crawler, dem Skript eines Nachhaltigkeitsprüfers. Eine reine HTML-Seite reicht nicht. Der Pass muss maschinenlesbar sein — eine strukturierte Nutzlast, die ein Programm parsen, verknüpfen und auswerten kann, ohne zu scrapen.

Dieser Leitfaden richtet sich an Entwickler mit der naheliegenden Anschlussfrage: Ich habe einen DPP — wie liest eine Maschine ihn tatsächlich? Die Antwort bei qr3 ist JSON-LD über den öffentlichen Resolver. Wir zeigen die echte Antwort, erklären, wie dieselbe URL Mensch und Maschine bedient, und ordnen dann EPCIS 2.0 — den komplementären GS1-Eventstandard — ein.

Was Maschinenlesbarkeit für einen DPP bedeutet

Maschinenlesbar ist mehr als „liefert JSON". Für einen Produktpass heißt es drei Dinge:

Strukturiert — Felder, die ein Parser adressieren kann (gtin, name, …), keine Prosa zum Scrapen.
Typisiert und verknüpft — Begriffe verankert in gemeinsamen Vokabularen, damit Product für alle dasselbe bedeutet. Das ist das Linked Data in JSON-LD.
Stabil abrufbar — eine dauerhafte URL pro Artikel, die ein Skript über die gesamte Produktlebensdauer per GET abfragen kann.

JSON-LD (JSON for Linking Data) liefert alle drei. Es ist gewöhnliches JSON plus einem @context, der jeden Schlüssel auf einen Begriff in einem öffentlichen Vokabular abbildet — hier schema.org und das GS1-Web-Vokabular. Ein Crawler, der schema.org bereits versteht, versteht den Pass ohne jede Sonderintegration.

Der DPP als JSON-LD (echtes curl + verifizierte Antwort)

Jeder qr3-Pass löst unter einer GS1-Digital-Link-URL auf: https://qr3.app/dpp/{gtin}/{serial}. Hänge ?format=jsonld an, um die Linked-Data-Ansicht anzufordern. Gegen die Live-Batterie-Demo:

curl -s "https://qr3.app/dpp/04019999999902/DEMO-BAT-01?format=jsonld"

liefert:

{
  "@context": ["https://schema.org", "https://gs1.org/voc/"],
  "@type": "Product",
  "gtin": "04019999999902",
  "name": "EcoMax 5000 (Demo)"
}

Drei Dinge fallen auf:

@context ist ein Array aus zwei Vokabularen — schema.org für das allgemeine Web und gs1.org/voc/ für die GS1-Produktbegriffe. Schlüssel lösen gegen beide auf.
@type: "Product" sagt jedem Linked-Data-Konsumenten exakt, um welche Art Entität es sich handelt.
Die Werte (gtin, name) sind echt und live — das ist die tatsächliche Nutzlast, kein Mock.

Genau das ist der Punkt: Das Skript eines Recyclers braucht keinen qr3-spezifischen Client. Es macht ein HTTP-GET, parst JSON-LD, das es ohnehin versteht, und liest GTIN und Produktname direkt heraus.

Eine URL, zwei Zielgruppen: Content Negotiation

Dieselbe URL https://qr3.app/dpp/{gtin}/{serial} bedient einen menschenfreundlichen HTML-Pass und die Maschinenansicht — der Server entscheidet anhand dessen, was der Aufrufer anfordert, was er zurückgibt. Zwei Wege zu fragen:

Du willst	Query-Parameter	Oder Accept-Header
Menschliche HTML-Seite	(Standard)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Schlichtes JSON	`?format=json`	—
Linkset (verwandte Ressourcen)	`?format=linkset`	—
DCAT-AP (Datensatz-Metadaten)	`?format=dcat-ap`	—

Eine Handykamera, die den QR öffnet, landet also auf dem lesbaren HTML-Pass, während ein Skript dieselbe URL nach application/ld+json fragt und strukturierte Daten erhält:

# Maschinenansicht per Header-Negotiation — gleiche URL, kein Query-String
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Ein Identifikator, eine URL, viele Repräsentationen. GTIN/Seriennummer bleibt stabil; die Ansicht passt sich dem Aufrufer an. Genau das macht einen DPP zugleich langlebig und interoperabel.

Wo EPCIS 2.0 hineinpasst (Events vs. Pass)

Eine häufige Anschlussfrage: Was ist mit EPCIS — ist das nicht der GS1-Standard dafür? Wichtige Unterscheidung:

Ein DPP ist die statische Beschreibung eines Produktartikels — seine Identität, Materialien, CO₂-Fußabdruck, Recyclingfähigkeit. Er beantwortet „Was ist dieses Ding?" Das obige JSON-LD ist dieser Schnappschuss.
EPCIS 2.0 ist der GS1-Standard für Lieferketten-Events — die Sichtbarkeitsdaten von was wann wo und warum geschah: ein Artikel wurde angelegt, versendet, empfangen, recycelt. Er beantwortet „Was geschah mit diesem Ding, und wo ist es?"

Sie sind komplementär, nicht konkurrierend. Der Pass sagt dir, dass das Produkt eine 5,2-kWh-Batterie mit 35 % Rezyklatanteil ist; eine EPCIS-Eventspur würde dir sagen, dass sie an einem bestimmten Tag in Hamburg gefertigt, über ein Verteilzentrum verschickt und bei einem Recycler angekommen ist. EPCIS 2.0 selbst ist JSON/JSON-LD-freundlich, sodass beide dasselbe Linked-Data-Weltbild und dieselben GS1-Identifikatoren (GTIN + Seriennummer) als Verknüpfungsschlüssel teilen.

qr3-Scope (präzise): qr3 gibt den DPP als JSON-LD aus — genau das zeigt dieser Beitrag. qr3 bietet kein EPCIS-Event-Capture und keine EPCIS-Endpunkte. Behandle EPCIS 2.0 hier als den konzeptionellen, komplementären Standard, den du neben einem DPP für vollständige Lieferketten-Rückverfolgbarkeit einsetzen würdest — nicht als qr3-Feature.

Das mentale Modell lautet also: Der DPP (qr3, JSON-LD) ist das Stammdatenblatt des Produkts; EPCIS 2.0 (separates System) ist sein Fahrtenbuch. Dieselben Identifikatoren, zwei beantwortete Fragen.

Einen DPP erzeugen, der JSON-LD bereitstellt

Du musst nichts Besonderes tun, um JSON-LD zu „aktivieren" — lege den Pass an, und der Resolver liefert automatisch jede Repräsentation:

import { QR3 } from "@qr3/sdk";

const client = new QR3({ apiKey: process.env.QR3_API_KEY! });

const passport = await client.dpp.create({
  gtin: "04019999999902",
  serial: "SN-00012345",
  product_name: "PowerCell 5 kWh LFP",
  manufacturer: "ExampleTech GmbH",
  origin_country: "DE",
  category: "battery",
  market_countries: ["DE", "FR", "AT"],
  status: "live",
  battery_data: {
    capacity_kwh: 5,
    carbon_footprint_kg: 62,
    recycled_content_pct: 12,
    recyclability_pct: 95,
  },
});

// Der Pass löst nun unter https://qr3.app/dpp/04019999999902/SN-00012345 auf.
// Menschen erhalten HTML; Maschinen hängen ?format=jsonld an (oder senden Accept: application/ld+json).
console.log(passport.qr.svg); // QR kodiert den GS1 Digital Link zum Resolver

Einmal angelegt, beantwortet die Artikel-URL sofort beide Zielgruppen — kein zusätzlicher Publish-Schritt für die Maschinenansicht.

FAQ

Warum JSON-LD und nicht schlichtes JSON? Schlichtes JSON ist strukturiert, aber nicht selbstbeschreibend: Ein Konsument muss deine Feldnamen lernen. JSON-LD ergänzt @context und bildet jeden Schlüssel auf schema.org-/GS1-Begriffe ab, sodass jeder Linked-Data-Konsument es ohne Sonderintegration versteht. Brauchst du nur einen schnellen Lesezugriff, steht weiterhin ?format=json bereit.

Implementiert qr3 EPCIS 2.0? Nein. qr3 gibt den DPP als JSON-LD aus. EPCIS 2.0 ist der separate, komplementäre GS1-Standard für Lieferketten-Events; du würdest ihn daneben betreiben, verknüpft über die gemeinsame GTIN + Seriennummer.

Wie bekomme ich die Maschinenansicht? Hänge ?format=jsonld an die Resolver-URL an oder sende Accept: application/ld+json. Beide liefern dieselbe Linked-Data-Nutzlast.

Ist der @context stabil? Er fixiert schema.org plus das GS1-Web-Vokabular (gs1.org/voc/) — beides öffentliche, versionierte Vokabulare, sodass sich Konsumenten auf die Begriffsbedeutungen verlassen können.

Quellen

Kostenlos starten und einen DPP erzeugen, der JSON-LD bereitstellt: app.qr3.app/sign-up