JSON-LD för digitala produktpass (och var EPCIS 2.0 passar in)

Ett digitalt produktpass är avsett att läsas av människor och av maskiner: ett återvinningsföretags mottagningssystem, ett tull-API, en marknadsplats-crawler, ett skript hos en hållbarhetsrevisor. En sida med enbart HTML för människor räcker inte. Passet måste vara maskinläsbart — en strukturerad nyttolast som ett program kan tolka, länka och resonera kring utan att skrapa.

Den här guiden är till för utvecklare som ställer den uppenbara följdfrågan: när jag väl har ett DPP, hur läser en maskin det egentligen? Svaret för qr3 är JSON-LD via den publika resolvern. Vi visar det verkliga svaret, förklarar hur samma URL betjänar människor och maskiner, och placerar sedan EPCIS 2.0 — den kompletterande GS1-händelsestandarden — i sitt sammanhang.

Vad maskinläsbarhet innebär för ett DPP

Maskinläsbart är mer än "returnerar JSON". För ett produktpass betyder det tre saker:

Strukturerat — fält som en parser kan adressera (gtin, name, …), inte prosa att skrapa.
Typat och länkat — termer förankrade i gemensamma vokabulärer så att Product betyder samma sak för alla. Det är Linked Data i JSON-LD.
Stabilt att hämta — en hållbar URL per artikel som ett skript kan göra GET mot under hela produktens livslängd.

JSON-LD (JSON for Linking Data) levererar alla tre. Det är vanlig JSON plus ett @context som mappar varje nyckel till en term i en publik vokabulär — här schema.org och GS1 Web Vocabulary. En crawler som redan förstår schema.org förstår passet utan någon som helst egen integration.

DPP:t som JSON-LD (verklig curl + verifierat svar)

Varje qr3-pass resolveras vid en GS1 Digital Link-URL: https://qr3.app/dpp/{gtin}/{serial}. Lägg till ?format=jsonld för att begära Linked Data-vyn. Mot den live-batteridemon:

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

returnerar:

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

Tre saker att notera:

@context är en array av två vokabulärer — schema.org för den allmänna webben och gs1.org/voc/ för GS1:s produkttermer. Nycklar resolveras mot båda.
@type: "Product" talar om för varje Linked Data-konsument exakt vilken sorts entitet detta är.
Värdena (gtin, name) är verkliga och live — detta är den faktiska nyttolasten, inte en attrapp.

Det är hela poängen: ett återvinningsföretags skript behöver ingen qr3-specifik klient. Det gör en HTTP-GET, tolkar JSON-LD som det redan förstår och läser av GTIN och produktnamn direkt.

En URL, två målgrupper: innehållsförhandling

Samma https://qr3.app/dpp/{gtin}/{serial}-URL betjänar ett människovänligt HTML-pass och maskinvyn — servern avgör vad som ska returneras utifrån vad anroparen efterfrågar. Två sätt att fråga:

Du vill ha	Query-parameter	Eller Accept-header
HTML-sida för människor	(standard)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Vanlig JSON	`?format=json`	—
Linkset (relaterade resurser)	`?format=linkset`	—
DCAT-AP (datamängdsmetadata)	`?format=dcat-ap`	—

Så en telefonkamera som öppnar QR-koden landar på det läsbara HTML-passet, medan ett skript frågar den identiska URL:en efter application/ld+json och får strukturerade data:

# Maskinvy via headerförhandling — samma URL, ingen query-sträng
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

En identifierare, en URL, många representationer. GTIN/serienummer förblir stabilt; vyn anpassar sig efter anroparen. Det är precis det som gör ett DPP både hållbart och interoperabelt på samma gång.

Var EPCIS 2.0 passar in (händelser kontra pass)

En vanlig följdfråga: hur är det med EPCIS — är inte det GS1-standarden för det här? Viktig distinktion:

Ett DPP är den statiska beskrivningen av en enskild produktartikel — dess identitet, material, koldioxidavtryck, återvinningsbarhet. Det besvarar "vad är den här saken?" JSON-LD ovan är just den ögonblicksbilden.
EPCIS 2.0 är GS1:s standard för händelser i leveranskedjan — synlighetsdata om vad som hände, var, när och varför: en artikel togs i bruk, skeppades, mottogs, återvanns. Det besvarar "vad hände med den här saken, och var finns den?"

De är kompletterande, inte konkurrerande. Passet talar om för dig att produkten är ett 5,2 kWh-batteri med 35 % återvunnet innehåll; ett EPCIS-händelsespår skulle tala om för dig att det tillverkades i Hamburg ett visst datum, skeppades via ett distributionscenter och anlände till ett återvinningsföretag. EPCIS 2.0 är i sig JSON/JSON-LD-vänligt, så de två delar samma Linked Data-världsbild och samma GS1-identifierare (GTIN + serienummer) som join-nyckel.

qr3:s omfattning (var precis): qr3 matar ut DPP:t som JSON-LD — det är vad det här inlägget demonstrerar. qr3 tillhandahåller inte EPCIS-händelseinsamling eller EPCIS-endpoints. Betrakta EPCIS 2.0 här som den konceptuella, kompletterande standard du skulle anta vid sidan av ett DPP för fullständig spårbarhet i leveranskedjan, inte som en qr3-funktion.

Så den mentala modellen är: DPP:t (qr3, JSON-LD) är produktens identitetsblad; EPCIS 2.0 (separat system) är dess resedagbok. Samma identifierare, två frågor besvarade.

Generera ett DPP som exponerar JSON-LD

Du behöver inte göra något särskilt för att "aktivera" JSON-LD — skapa passet så betjänar resolvern varje representation automatiskt:

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 väl är skapat besvarar artikelns URL båda målgrupperna omedelbart — inget extra publiceringssteg för maskinvyn.

FAQ

Varför JSON-LD och inte vanlig JSON? Vanlig JSON är strukturerad men inte självbeskrivande: en konsument måste lära sig dina fältnamn. JSON-LD lägger till @context, som mappar varje nyckel till schema.org-/GS1-termer, så att vilken Linked Data-konsument som helst förstår det utan en egen integration. Om du bara behöver en snabb läsning finns ?format=json fortfarande tillgängligt.

Implementerar qr3 EPCIS 2.0? Nej. qr3 matar ut DPP:t som JSON-LD. EPCIS 2.0 är den separata, kompletterande GS1-standarden för händelser i leveranskedjan; du skulle köra den vid sidan av, sammanfogad via det gemensamma GTIN + serienummer.

Hur får jag maskinvyn? Lägg till ?format=jsonld i resolver-URL:en, eller skicka Accept: application/ld+json. Båda returnerar samma Linked Data-nyttolast.

Är @context stabilt? Det fäster schema.org plus GS1 Web Vocabulary (gs1.org/voc/) — båda publika, versionerade vokabulärer, så att konsumenter kan förlita sig på termernas betydelser.

Källor

Börja gratis och skapa ett DPP som exponerar JSON-LD: app.qr3.app/sign-up