JSON-LD digitaalisille tuotepasseille (ja mihin EPCIS 2.0 sopii)

Digitaalinen tuotepassi on tarkoitettu sekä ihmisten että koneiden luettavaksi: kierrättäjän vastaanottojärjestelmän, tullin API:n, markkinapaikan indeksointirobotin tai kestävyysauditoijan skriptin. Pelkkä ihmisille tarkoitettu HTML-sivu ei riitä. Passin on oltava koneluettava — rakenteinen tietopaketti, jonka ohjelma voi jäsentää, linkittää ja päätellä ilman raapimista.

Tämä opas on tarkoitettu kehittäjille, jotka esittävät seuraavan ilmeisen kysymyksen: kun minulla on DPP, miten kone oikeasti lukee sen? Vastaus qr3:lle on JSON-LD julkisen resolverin kautta. Näytämme todellisen vastauksen, selitämme, kuinka sama URL palvelee ihmisiä ja koneita, ja asetamme sitten EPCIS 2.0:n — täydentävän GS1-tapahtumastandardin — oikeaan asiayhteyteen.

Mitä koneluettavuus tarkoittaa DPP:lle

Koneluettavuus on enemmän kuin "palauttaa JSON:ia". Tuotepassille se tarkoittaa kolmea asiaa:

Rakenteinen — kentät, joihin jäsentäjä voi viitata (gtin, name, …), ei raavittavaa proosaa.
Tyypitetty ja linkitetty — termit ankkuroitu yhteisiin sanastoihin, jotta Product tarkoittaa kaikille samaa. Tämä on JSON-LD:n linkitetty data (Linked Data).
Vakaa noutaa — yksi pysyvä URL per tuoteyksikkö, jonka skripti voi GET-kutsua tuotteen koko elinkaaren ajan.

JSON-LD (JSON for Linking Data) tarjoaa kaikki kolme. Se on tavallista JSON:ia lisättynä @context-osalla, joka kytkee jokaisen avaimen julkisen sanaston termiin — tässä schema.org ja GS1 Web Vocabulary. Indeksointirobotti, joka jo ymmärtää schema.org:n, ymmärtää passin ilman lainkaan mukautettua integraatiota.

DPP JSON-LD:nä (todellinen curl + varmennettu vastaus)

Jokainen qr3-passi resolvoituu GS1 Digital Link -URL-osoitteessa: https://qr3.app/dpp/{gtin}/{serial}. Lisää ?format=jsonld pyytääksesi linkitetyn datan näkymää. Live-akkudemoa vastaan:

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

palauttaa:

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

Kolme huomioitavaa asiaa:

@context on kahden sanaston taulukko — schema.org yleistä verkkoa varten ja gs1.org/voc/ GS1:n tuotetermejä varten. Avaimet resolvoituvat kumpaakin vasten.
@type: "Product" kertoo mille tahansa linkitetyn datan kuluttajalle tarkasti, minkä tyyppinen entiteetti tämä on.
Arvot (gtin, name) ovat todellisia ja eläviä — tämä on todellinen tietopaketti, ei mallinnus.

Siinä koko pointti: kierrättäjän skripti ei tarvitse qr3-erityistä asiakasta. Se tekee HTTP GET-kutsun, jäsentää JSON-LD:n, jonka se jo ymmärtää, ja lukee GTIN:n ja tuotenimen suoraan.

Yksi URL, kaksi yleisöä: sisältöneuvottelu

Sama https://qr3.app/dpp/{gtin}/{serial} -URL palvelee sekä ihmisystävällistä HTML-passia että koneen näkymää — palvelin päättää, mitä palauttaa sen perusteella, mitä kutsuja pyytää. Kaksi tapaa pyytää:

Haluat	Kyselyparametri	Tai Accept-otsake
Ihmisille tarkoitettu HTML-sivu	(oletus)	`Accept: text/html`
JSON-LD (linkitetty data)	`?format=jsonld`	`Accept: application/ld+json`
Tavallinen JSON	`?format=json`	—
Linkset (liittyvät resurssit)	`?format=linkset`	—
DCAT-AP (datasetin metatiedot)	`?format=dcat-ap`	—

Joten puhelimen kamera, joka avaa QR-koodin, päätyy luettavalle HTML-passille, kun taas skripti pyytää identtiseltä URL-osoitteelta muotoa application/ld+json ja saa rakenteista dataa:

# Koneen näkymä otsakeneuvottelun kautta — sama URL, ei kyselymerkkijonoa
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Yksi tunniste, yksi URL, monta esitysmuotoa. GTIN/sarjanumero pysyy vakaana; näkymä mukautuu kutsujaan. Juuri tämä tekee DPP:stä samanaikaisesti pysyvän ja yhteentoimivan.

Mihin EPCIS 2.0 sopii (tapahtumat vs. passi)

Yleinen jatkokysymys: entä EPCIS — eikö se ole GS1-standardi tähän? Tärkeä ero:

DPP on yhden tuoteyksikön staattinen kuvaus — sen identiteetti, materiaalit, hiilijalanjälki, kierrätettävyys. Se vastaa kysymykseen "mikä tämä asia on?" Yllä oleva JSON-LD on tämä tilannekuva.
EPCIS 2.0 on GS1:n standardi toimitusketjun tapahtumille — näkyvyysdata siitä, mitä tapahtui, missä, milloin ja miksi: tuote luotiin, lähetettiin, vastaanotettiin, kierrätettiin. Se vastaa kysymykseen "mitä tälle asialle tapahtui ja missä se on?"

Ne ovat täydentäviä, eivät kilpailevia. Passi kertoo, että tuote on 5,2 kWh:n akku, jossa on 35 % kierrätettyä sisältöä; EPCIS-tapahtumajälki kertoisi, että se valmistettiin Hampurissa tiettynä päivänä, kuljetettiin jakelukeskuksen kautta ja saapui kierrättäjälle. EPCIS 2.0 itsessään on JSON/JSON-LD-ystävällinen, joten nämä kaksi jakavat saman linkitetyn datan maailmankuvan ja samat GS1-tunnisteet (GTIN + sarjanumero) liitosavaimena.

qr3:n laajuus (ole tarkka): qr3 tuottaa DPP:n JSON-LD:nä — juuri sitä tämä kirjoitus havainnollistaa. qr3 ei tarjoa EPCIS-tapahtumien keräystä tai EPCIS-päätepisteitä. Käsittele EPCIS 2.0:aa tässä käsitteellisenä, täydentävänä standardina, jonka ottaisit käyttöön DPP:n rinnalla täyttä toimitusketjun jäljitettävyyttä varten, ei qr3-ominaisuutena.

Joten ajatusmalli on: DPP (qr3, JSON-LD) on tuotteen identiteettilomake; EPCIS 2.0 (erillinen järjestelmä) on sen matkapäiväkirja. Samat tunnisteet, kaksi vastattua kysymystä.

DPP:n luominen, joka tarjoaa JSON-LD:n

Et tee mitään erityistä "ottaaksesi käyttöön" JSON-LD:n — luo passi, ja resolveri palvelee jokaisen esitysmuodon automaattisesti:

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

Kun passi on luotu, tuoteyksikön URL vastaa molemmille yleisöille välittömästi — ei ylimääräistä julkaisuvaihetta koneen näkymälle.

FAQ

Miksi JSON-LD eikä tavallinen JSON? Tavallinen JSON on rakenteinen mutta ei itsekuvaava: kuluttajan on opeteltava kenttiesi nimet. JSON-LD lisää @context-osan, joka kytkee jokaisen avaimen schema.org- / GS1-termeihin, joten mikä tahansa linkitetyn datan kuluttaja ymmärtää sen ilman mukautettua integraatiota. Jos tarvitset vain nopean luennan, ?format=json on edelleen saatavilla.

Toteuttaako qr3 EPCIS 2.0:n? Ei. qr3 tuottaa DPP:n JSON-LD:nä. EPCIS 2.0 on erillinen, täydentävä GS1-standardi toimitusketjun tapahtumille; ajaisit sitä rinnalla, liitettynä jaetulla GTIN:llä + sarjanumerolla.

Miten saan koneen näkymän? Lisää ?format=jsonld resolverin URL-osoitteeseen tai lähetä Accept: application/ld+json. Kumpikin palauttaa saman linkitetyn datan tietopaketin.

Onko @context vakaa? Se kiinnittää schema.org:n sekä GS1 Web Vocabularyn (gs1.org/voc/) — molemmat julkisia, versioituja sanastoja, joten kuluttajat voivat luottaa termien merkityksiin.

Lähteet

Aloita ilmaiseksi ja luo DPP, joka tarjoaa JSON-LD:n: app.qr3.app/sign-up