JSON-LD til digitale produktpas (og hvor EPCIS 2.0 passer ind)

Et digitalt produktpas er beregnet til at blive læst af mennesker og af maskiner: en genvindingsvirksomheds modtagesystem, en told-API, en marketplace-crawler, et bæredygtighedsrevisorscript. En HTML-side udelukkende for mennesker er ikke nok. Passet skal være maskinlæsbart — en struktureret payload, som et program kan parse, sammenkæde og ræsonnere over uden at scrape.

Denne guide henvender sig til udviklere, der stiller det oplagte næste spørgsmål: når jeg først har et DPP, hvordan læser en maskine det så faktisk? Svaret for qr3 er JSON-LD via den offentlige resolver. Vi viser det rigtige svar, forklarer, hvordan den samme URL betjener mennesker og maskiner, og placerer derefter EPCIS 2.0 — det komplementære GS1-eventstandard — i kontekst.

Hvad maskinlæsbarhed betyder for et DPP

Maskinlæsbar er mere end "returnerer JSON". For et produktpas betyder det tre ting:

Struktureret — felter, som en parser kan adressere (gtin, name, …), ikke prosa, der skal scrapes.
Typet og sammenkædet — termer forankret i fælles vokabularer, så Product betyder det samme for alle. Det er Linked Data i JSON-LD.
Stabil at hente — én holdbar URL pr. vare, som et script kan lave et GET mod gennem hele produktets levetid.

JSON-LD (JSON for Linking Data) leverer alle tre. Det er almindelig JSON plus en @context, der knytter hver nøgle til en term i et offentligt vokabular — her schema.org og GS1 Web Vocabulary. En crawler, der allerede forstår schema.org, forstår passet med nul brugerdefineret integration.

DPP'et som JSON-LD (rigtig curl + verificeret svar)

Hvert qr3-pas resolves på en GS1 Digital Link-URL: https://qr3.app/dpp/{gtin}/{serial}. Tilføj ?format=jsonld for at bede om Linked Data-visningen. Mod det live batteridemo:

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

returnerer:

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

Tre ting at bemærke:

@context er et array med to vokabularer — schema.org til det generelle web og gs1.org/voc/ til GS1's produkttermer. Nøgler resolves mod begge.
@type: "Product" fortæller enhver Linked Data-forbruger præcist, hvilken slags entitet dette er.
Værdierne (gtin, name) er rigtige og live — dette er den faktiske payload, ikke en mock.

Det er hele pointen: en genvindingsvirksomheds script behøver ikke en qr3-specifik klient. Det laver et HTTP-GET, parser JSON-LD, som det allerede forstår, og aflæser GTIN og produktnavn direkte.

Én URL, to målgrupper: content negotiation

Den samme https://qr3.app/dpp/{gtin}/{serial}-URL betjener et menneskevenligt HTML-pas og maskinvisningen — serveren afgør, hvad der skal returneres, ud fra hvad kalderen beder om. To måder at spørge på:

Du ønsker	Query-parameter	Eller Accept-header
Menneskelig HTML-side	(standard)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Almindelig JSON	`?format=json`	—
Linkset (relaterede ressourcer)	`?format=linkset`	—
DCAT-AP (datasætmetadata)	`?format=dcat-ap`	—

Så et telefonkamera, der åbner QR-koden, lander på det læsbare HTML-pas, mens et script beder den identiske URL om application/ld+json og får struktureret data:

# Maskinvisning via header-negotiation — samme URL, ingen query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Én identifikator, én URL, mange repræsentationer. GTIN/serienummer forbliver stabilt; visningen tilpasser sig kalderen. Det er netop det, der gør et DPP holdbart og interoperabelt på samme tid.

Hvor EPCIS 2.0 passer ind (events vs. pas)

Et almindeligt opfølgende spørgsmål: hvad med EPCIS — er det ikke GS1-standarden for dette? Vigtig sondring:

Et DPP er den statiske beskrivelse af én produktvare — dens identitet, materialer, CO2-aftryk, genanvendelighed. Det besvarer "hvad er denne ting?" JSON-LD'en ovenfor er det øjebliksbillede.
EPCIS 2.0 er GS1's standard for forsyningskædeevents — synlighedsdata om hvad der skete, hvor, hvornår og hvorfor: en vare blev oprettet, afsendt, modtaget, genvundet. Det besvarer "hvad er der sket med denne ting, og hvor er den?"

De er komplementære, ikke konkurrerende. Passet fortæller dig, at produktet er et 5,2 kWh-batteri med 35 % genanvendt indhold; et EPCIS-eventspor ville fortælle dig, at det blev fremstillet i Hamborg på en given dato, afsendt gennem et distributionscenter og ankom til en genvindingsvirksomhed. EPCIS 2.0 er selv JSON/JSON-LD-venligt, så de to deler samme Linked Data-verdensbillede og de samme GS1-identifikatorer (GTIN + serienummer) som join-nøgle.

qr3-scope (vær præcis): qr3 udsender DPP'et som JSON-LD — det er det, dette indlæg demonstrerer. qr3 leverer ikke EPCIS-eventopfangning eller EPCIS-endpoints. Betragt EPCIS 2.0 her som den konceptuelle, komplementære standard, du ville indføre sideløbende med et DPP for fuld forsyningskædesporbarhed, ikke som en qr3-funktion.

Så den mentale model er: DPP'et (qr3, JSON-LD) er produktets identitetsark; EPCIS 2.0 (separat system) er dets rejselog. Samme identifikatorer, to spørgsmål besvaret.

Generering af et DPP, der eksponerer JSON-LD

Du gør ikke noget særligt for at "aktivere" JSON-LD — opret passet, og resolveren betjener automatisk hver 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,
  },
});

// The passport now resolves at https://qr3.app/dpp/04019999999902/SN-00012345
// Humans get HTML; machines append ?format=jsonld (or send Accept: application/ld+json).
console.log(passport.qr.svg); // QR encodes the GS1 Digital Link to the resolver

Når det først er oprettet, besvarer varens URL straks begge målgrupper — intet ekstra publiceringstrin for maskinvisningen.

FAQ

Hvorfor JSON-LD og ikke almindelig JSON? Almindelig JSON er struktureret, men ikke selvbeskrivende: en forbruger skal lære dine feltnavne. JSON-LD tilføjer @context, der knytter hver nøgle til schema.org-/GS1-termer, så enhver Linked Data-forbruger forstår det uden en brugerdefineret integration. Hvis du blot har brug for en hurtig aflæsning, er ?format=json stadig tilgængelig.

Implementerer qr3 EPCIS 2.0? Nej. qr3 udsender DPP'et som JSON-LD. EPCIS 2.0 er den separate, komplementære GS1-standard for forsyningskæde-events; du ville køre den sideløbende, sammenkædet via den fælles GTIN + serienummer.

Hvordan får jeg maskinvisningen? Tilføj ?format=jsonld til resolver-URL'en, eller send Accept: application/ld+json. Begge returnerer samme Linked Data-payload.

Er @context stabil? Den fastlåser schema.org plus GS1 Web Vocabulary (gs1.org/voc/) — begge offentlige, versionerede vokabularer, så forbrugere kan stole på betydningen af termerne.

Kilder

Start gratis og opret et DPP, der eksponerer JSON-LD: app.qr3.app/sign-up