JSON-LD digitaalsete tootepasside jaoks (ja kus on EPCIS 2.0 koht)

Digitaalne tootepass on mõeldud lugemiseks nii inimestele kui ka masinatele: ringlusseandja vastuvõtusüsteemile, tolli API-le, kauplemisplatvormi indekseerijale, jätkusuutlikkuse audiitori skriptile. Ainult inimesele mõeldud HTML-leht ei piisa. Pass peab olema masinloetav — struktureeritud andmehulk, mida programm saab parsida, linkida ja mille üle arutleda ilma kraapimiseta.

See juhend on mõeldud arendajatele, kes esitavad ilmselge järgmise küsimuse: kui mul on DPP olemas, siis kuidas masin seda tegelikult loeb? qr3 vastus on JSON-LD avaliku resolveri kaudu. Näitame tegelikku vastust, selgitame, kuidas üksainus URL teenindab inimesi ja masinaid, ning seejärel asetame konteksti EPCIS 2.0 — täiendava GS1 sündmusstandardi.

Mida masinloetavus DPP jaoks tähendab

Masinloetavus on enamat kui "tagastab JSON-i". Tootepassi puhul tähendab see kolme asja:

Struktureeritud — väljad, mille poole parser saab pöörduda (gtin, name, …), mitte kraabitav proosa.
Tüübitatud ja lingitud — terminid, mis on ankurdatud jagatud sõnastikega, nii et Product tähendab kõigi jaoks sama. See on JSON-LD lingitud andmete (Linked Data) osa.
Stabiilne pärida — üks püsiv URL toote kohta, mida skript saab kogu toote eluea jooksul GET-ida.

JSON-LD (JSON for Linking Data) pakub kõiki kolme. See on tavaline JSON, millele lisandub @context, mis kaardistab iga võtme terminiks avalikus sõnastikus — siin schema.org ja GS1 Web Vocabulary. Indekseerija, kes juba mõistab schema.org-i, mõistab passi ilma igasuguse kohandatud lõimimiseta.

DPP kui JSON-LD (tegelik curl + kontrollitud vastus)

Iga qr3 pass laheneb GS1 Digital Linki URL-il: https://qr3.app/dpp/{gtin}/{serial}. Lingitud-andmete vaate küsimiseks lisa ?format=jsonld. Live-aku demo vastu:

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

tagastab:

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

Kolm tähelepanekut:

@context on kahe sõnastiku massiiv — schema.org üldveebi jaoks ja gs1.org/voc/ GS1 tooteterminite jaoks. Võtmed lahenevad mõlema vastu.
@type: "Product" ütleb igale lingitud-andmete tarbijale täpselt, mis tüüpi olemiga on tegemist.
Väärtused (gtin, name) on tegelikud ja live — see on tegelik andmehulk, mitte makett.

Selles ongi kogu mõte: ringlusseandja skript ei vaja qr3-spetsiifilist klienti. See teeb HTTP GET-i, parsib JSON-LD-d, mida ta juba mõistab, ja loeb GTIN-i ning tootenime otse välja.

Üks URL, kaks sihtrühma: sisuläbirääkimised

Sama https://qr3.app/dpp/{gtin}/{serial} URL teenindab inimsõbralikku HTML-passi ja masinvaadet — server otsustab, mida tagastada, selle põhjal, mida helistaja küsib. Küsida saab kahel viisil:

Mida soovid	Päringuparameeter	Või Accept-päis
Inimesele mõeldud HTML-leht	(vaikimisi)	`Accept: text/html`
JSON-LD (lingitud andmed)	`?format=jsonld`	`Accept: application/ld+json`
Tavaline JSON	`?format=json`	—
Linkset (seotud ressursid)	`?format=linkset`	—
DCAT-AP (andmestiku metaandmed)	`?format=dcat-ap`	—

Nii jõuab telefonikaamera, mis QR-i avab, loetavale HTML-passile, samal ajal kui skript küsib identselt URL-ilt application/ld+json-i ja saab struktureeritud andmed:

# Masinvaade päiseläbirääkimiste kaudu — sama URL, ilma päringustringita
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Üks identifikaator, üks URL, palju esitusi. GTIN/seerianumber jääb stabiilseks; vaade kohandub helistajale. Just see teebki DPP korraga püsivaks ja koostalitlusvõimeliseks.

Kus on EPCIS 2.0 koht (sündmused vs. pass)

Levinud järelküsimus: aga EPCIS — kas see pole mitte GS1 standard selle jaoks? Oluline eristus:

DPP on ühe tooteüksuse staatiline kirjeldus — selle identiteet, materjalid, süsinikujalajälg, ringlussevõetavus. See vastab küsimusele "mis asi see on?" Ülaltoodud JSON-LD ongi see hetktõmmis.
EPCIS 2.0 on GS1 standard tarneahela sündmuste jaoks — nähtavusandmed selle kohta, mis juhtus, kus, millal ja miks: üksus võeti kasutusele, saadeti teele, võeti vastu, suunati ringlusse. See vastab küsimusele "mis juhtus selle asjaga ja kus see asub?"

Need on täiendavad, mitte konkureerivad. Pass ütleb sulle, et toode on 5,2 kWh aku, milles on 35% ringlusmaterjali; EPCIS-i sündmuste jälg ütleks sulle, et see toodeti Hamburgis kindlal kuupäeval, saadeti teele läbi jaotuskeskuse ja jõudis ringlusseandjani. EPCIS 2.0 ise on JSON/JSON-LD-sõbralik, nii et need kaks jagavad sama lingitud-andmete maailmapilti ja samu GS1 identifikaatoreid (GTIN + seerianumber) ühendusvõtmena.

qr3 ulatus (ole täpne): qr3 väljastab DPP JSON-LD-na — just seda see postitus demonstreerib. qr3 ei paku EPCIS-i sündmuste hõivet ega EPCIS-i lõpp-punkte. Käsitle EPCIS 2.0-d siin kui kontseptuaalset, täiendavat standardit, mille võtaksid täieliku tarneahela jälgitavuse saavutamiseks kasutusele DPP kõrval, mitte kui qr3 funktsiooni.

Mõtteline mudel on seega selline: DPP (qr3, JSON-LD) on toote identiteedileht; EPCIS 2.0 (eraldi süsteem) on selle reisipäevik. Samad identifikaatorid, kaks vastatud küsimust.

DPP genereerimine, mis avaldab JSON-LD-d

Sa ei tee JSON-LD "lubamiseks" midagi erilist — loo pass ja resolver teenindab kõiki esitusi automaatselt:

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

Pärast loomist vastab üksuse URL mõlemale sihtrühmale kohe — masinvaate jaoks pole vaja eraldi avaldamise sammu.

KKK

Miks JSON-LD, mitte tavaline JSON? Tavaline JSON on struktureeritud, kuid mitte iseennast kirjeldav: tarbija peab sinu väljanimed ära õppima. JSON-LD lisab @context-i, mis kaardistab iga võtme schema.org / GS1 terminitega, nii et iga lingitud-andmete tarbija mõistab seda ilma kohandatud lõimimiseta. Kui vajad ainult kiiret lugemist, on ?format=json endiselt saadaval.

Kas qr3 rakendab EPCIS 2.0-d? Ei. qr3 väljastab DPP JSON-LD-na. EPCIS 2.0 on eraldi, täiendav GS1 standard tarneahela sündmuste jaoks; sa käitaksid seda kõrvuti, ühendatuna jagatud GTIN-i + seerianumbri kaudu.

Kuidas ma masinvaate kätte saan? Lisa resolveri URL-ile ?format=jsonld või saada Accept: application/ld+json. Mõlemad tagastavad sama lingitud-andmete andmehulga.

Kas @context on stabiilne? See fikseerib schema.org-i pluss GS1 Web Vocabulary (gs1.org/voc/) — mõlemad on avalikud, versioonitud sõnastikud, nii et tarbijad saavad terminite tähendustele tugineda.

Allikad

Alusta tasuta ja loo DPP, mis avaldab JSON-LD-d: app.qr3.app/sign-up