JSON-LD skaitmeniniams gaminių pasams (ir kur tinka EPCIS 2.0)

Skaitmeninis gaminio pasas turi būti skaitomas ir žmonių, ir mašinų: perdirbėjo priėmimo sistemos, muitinės API, prekyvietės naršyklės, tvarumo auditoriaus skripto. Vien tik žmogui skirto HTML puslapio nepakanka. Pasas turi būti nuskaitomas mašinos — struktūrizuotas duomenų krūvis, kurį programa gali analizuoti, susieti ir apie jį samprotauti be turinio nukrapštymo.

Šis vadovas skirtas kūrėjams, užduodantiems akivaizdų kitą klausimą: kai jau turiu DPP, kaip mašina jį iš tiesų perskaito? qr3 atsakymas — JSON-LD per viešą skiriamąjį serverį. Parodysime tikrąjį atsakymą, paaiškinsime, kaip tas pats URL aptarnauja žmones ir mašinas, o tada įvesime į kontekstą EPCIS 2.0 — papildomą GS1 įvykių standartą.

Ką DPP reiškia nuskaitomumas mašinos

Nuskaitomas mašinos yra daugiau nei „grąžina JSON". Gaminio pasui tai reiškia tris dalykus:

Struktūrizuotas — laukai, į kuriuos analizatorius gali kreiptis (gtin, name, …), o ne tekstas, kurį reikia nukrapštyti.
Tipizuotas ir susietas — terminai, pririšti prie bendrų žodynų, kad Product reikštų tą patį visiems. Tai ir yra susietieji duomenys (Linked Data) JSON-LD formate.
Stabilus gauti — vienas patvarus URL kiekvienam vienetui, kurį skriptas gali GET per visą gaminio gyvavimo ciklą.

JSON-LD (JSON for Linking Data) suteikia visus tris. Tai įprastas JSON plius @context, kuris kiekvieną raktą susieja su terminu viešame žodyne — čia schema.org ir GS1 internetiniame žodyne. Naršyklė, kuri jau supranta schema.org, supranta ir pasą be jokios papildomos integracijos.

DPP kaip JSON-LD (tikras curl + patikrintas atsakymas)

Kiekvienas qr3 pasas pasiekiamas per GS1 Digital Link URL: https://qr3.app/dpp/{gtin}/{serial}. Pridėkite ?format=jsonld, kad paprašytumėte susietųjų duomenų vaizdo. Pasinaudojus veikiančia akumuliatoriaus demonstracija:

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

grąžina:

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

Trys dalykai, į kuriuos verta atkreipti dėmesį:

@context yra dviejų žodynų masyvas — schema.org bendrajam internetui ir gs1.org/voc/ GS1 gaminių terminams. Raktai sprendžiami pagal abu.
@type: "Product" bet kuriam susietųjų duomenų vartotojui tiksliai nurodo, kokio tipo tai esinys.
Reikšmės (gtin, name) yra tikros ir gyvos — tai faktinis duomenų krūvis, o ne imitacija.

Tai ir yra visa esmė: perdirbėjo skriptui nereikia qr3 specifinio kliento. Jis atlieka HTTP GET, analizuoja JSON-LD, kurį jau supranta, ir tiesiogiai nuskaito GTIN bei gaminio pavadinimą.

Vienas URL, dvi auditorijos: turinio derinimas

Tas pats https://qr3.app/dpp/{gtin}/{serial} URL aptarnauja žmogui draugišką HTML pasą ir mašinos vaizdą — serveris sprendžia, ką grąžinti, pagal tai, ko prašo iškvietėjas. Du būdai paprašyti:

Ko norite	Užklausos parametras	Arba Accept antraštė
Žmogui skirtas HTML puslapis	(numatytasis)	`Accept: text/html`
JSON-LD (susietieji duomenys)	`?format=jsonld`	`Accept: application/ld+json`
Paprastas JSON	`?format=json`	—
Linkset (susiję ištekliai)	`?format=linkset`	—
DCAT-AP (rinkinio metaduomenys)	`?format=dcat-ap`	—

Taigi telefono kamera, atverianti QR kodą, patenka į skaitomą HTML pasą, o skriptas tą patį URL prašo application/ld+json ir gauna struktūrizuotus duomenis:

# Mašinos vaizdas per antraštės derinimą — tas pats URL, jokios užklausos eilutės
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Vienas identifikatorius, vienas URL, daug atvaizdavimų. GTIN/serijos numeris lieka stabilus; vaizdas prisitaiko prie iškvietėjo. Būtent tai vienu metu daro DPP ir patvarų, ir sąveikų.

Kur tinka EPCIS 2.0 (įvykiai ir pasas)

Dažnas tolesnis klausimas: o kaip dėl EPCIS — argi tai ne GS1 standartas šiam tikslui? Svarbus skirtumas:

DPP yra statinis vieno gaminio vieneto aprašymas — jo tapatybė, medžiagos, anglies pėdsakas, perdirbamumas. Jis atsako į klausimą „kas yra šis daiktas?" Aukščiau pateiktas JSON-LD yra ta momentinė nuotrauka.
EPCIS 2.0 yra GS1 standartas tiekimo grandinės įvykiams — matomumo duomenims apie tai, kas įvyko, kur, kada ir kodėl: vienetas buvo paleistas naudoti, išsiųstas, gautas, perdirbtas. Jis atsako į klausimą „kas atsitiko šiam daiktui ir kur jis yra?"

Jie yra papildomi, o ne konkuruojantys. Pasas pasako, kad gaminys yra 5,2 kWh akumuliatorius su 35 % perdirbtos medžiagos; EPCIS įvykių pėdsakas pasakytų, kad jis buvo pagamintas Hamburge tam tikrą dieną, gabentas per paskirstymo centrą ir atvyko pas perdirbėją. Pats EPCIS 2.0 yra draugiškas JSON/JSON-LD formatams, todėl abu turi tą pačią susietųjų duomenų pasaulėžiūrą ir tuos pačius GS1 identifikatorius (GTIN + serijos numerį) kaip sujungimo raktą.

qr3 apimtis (būkite tikslūs): qr3 išveda DPP kaip JSON-LD — būtent tai demonstruoja šis įrašas. qr3 neteikia EPCIS įvykių fiksavimo ar EPCIS galinių taškų. EPCIS 2.0 čia laikykite konceptualiu, papildomu standartu, kurį pritaikytumėte kartu su DPP visapusiškam tiekimo grandinės atsekamumui, o ne qr3 funkcija.

Taigi mintinis modelis yra toks: DPP (qr3, JSON-LD) yra gaminio tapatybės lapas; EPCIS 2.0 (atskira sistema) yra jo kelionės žurnalas. Tie patys identifikatoriai, atsakyti du klausimai.

DPP, pateikiančio JSON-LD, generavimas

Nieko ypatingo „įjungti" JSON-LD daryti nereikia — sukurkite pasą ir skiriamasis serveris automatiškai aptarnaus kiekvieną atvaizdavimą:

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

Sukūrus, vieneto URL iškart atsako abiem auditorijoms — mašinos vaizdui nereikia jokio papildomo publikavimo žingsnio.

DUK

Kodėl JSON-LD, o ne paprastas JSON? Paprastas JSON yra struktūrizuotas, bet ne savaime aprašantis: vartotojas turi išmokti jūsų laukų pavadinimus. JSON-LD prideda @context, susiejantį kiekvieną raktą su schema.org / GS1 terminais, todėl bet kuris susietųjų duomenų vartotojas jį supranta be papildomos integracijos. Jei jums tereikia greito nuskaitymo, vis tiek prieinama ?format=json.

Ar qr3 įgyvendina EPCIS 2.0? Ne. qr3 išveda DPP kaip JSON-LD. EPCIS 2.0 yra atskiras, papildomas GS1 standartas tiekimo grandinės įvykiams; jį naudotumėte greta, susietą bendru GTIN + serijos numeriu.

Kaip gauti mašinos vaizdą? Prie skiriamojo serverio URL pridėkite ?format=jsonld arba siųskite Accept: application/ld+json. Abu grąžina tą patį susietųjų duomenų krūvį.

Ar @context yra stabilus? Jis pririša schema.org plius GS1 internetinį žodyną (gs1.org/voc/) — abu vieši, versijuoti žodynai, todėl vartotojai gali pasikliauti terminų reikšmėmis.

Šaltiniai

Pradėkite nemokamai ir sukurkite DPP, pateikiantį JSON-LD: app.qr3.app/sign-up