5 min branja Tutorials dpp json-ld epcis gs1-digital-link interoperability

JSON-LD za digitalne potne liste izdelkov (in kam sodi EPCIS 2.0)

DPP je strojem uporaben le, če je strojno berljiv. Ta vodnik prikazuje pravi JSON-LD, ki ga potni list qr3 izpostavi prek živega razreševalnika, kako en sam URL prek pogajanja o vsebini streže tako ljudem kot strojem in kam sodi dopolnilni dogodkovni standard EPCIS 2.0.

avtor QR3 Redaktion

JSON-LD za digitalne potne liste izdelkov (in kam sodi EPCIS 2.0)

Digitalni potni list izdelka je namenjen branju ljudi in strojev: prevzemnega sistema reciklažnega obrata, carinskega API-ja, pajka tržnice, skripte presojevalca trajnostnosti. Stran HTML, namenjena zgolj ljudem, ne zadošča. Potni list mora biti strojno berljiv — strukturirana vsebina, ki jo program lahko razčleni, poveže in iz nje sklepa brez postopka zajemanja (scrapinga).

Ta vodnik je za razvijalce, ki si zastavljajo očitno naslednje vprašanje: ko že imam DPP, kako ga stroj dejansko prebere? Odgovor za qr3 je JSON-LD prek javnega razreševalnika. Prikazali bomo pravi odziv, razložili, kako isti URL streže ljudem in strojem, in nato umestili EPCIS 2.0 — dopolnilni dogodkovni standard GS1 — v kontekst.

Kaj za DPP pomeni strojna berljivost

Strojna berljivost je več kot le "vrne JSON". Za potni list izdelka pomeni tri stvari:

  • Strukturiranost — polja, ki jih razčlenjevalnik lahko naslovi (gtin, name, …), in ne proza za zajemanje.
  • Tipiziranost in povezanost — izrazi, zasidrani v skupnih besednjakih, tako da Product pomeni isto vsem. To je povezani podatki (Linked Data) v JSON-LD.
  • Stabilnost pri prenosu — en trajen URL na izdelek, ki ga skripta lahko prek GET pridobi za celotno življenjsko dobo izdelka.

JSON-LD (JSON for Linking Data) zagotavlja vse tri. Gre za običajen JSON, ki mu je dodan @context, ki vsak ključ preslika v izraz v javnem besednjaku — tu sta to schema.org in spletni besednjak GS1. Pajek, ki schema.org že razume, brez kakršne koli integracije po meri razume tudi potni list.

DPP kot JSON-LD (pravi curl + preverjen odziv)

Vsak potni list qr3 se razreši na URL-ju GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Dodajte ?format=jsonld, da zahtevate pogled povezanih podatkov. Pri živi predstavitveni bateriji:

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

vrne:

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

Tri stvari, ki jih velja izpostaviti:

  • @context je polje dveh besednjakov — schema.org za splošni splet in gs1.org/voc/ za izraze izdelkov GS1. Ključi se razrešijo glede na oba.
  • @type: "Product" vsakemu uporabniku povezanih podatkov natančno pove, za kakšno vrsto entitete gre.
  • Vrednosti (gtin, name) so resnične in žive — to je dejanska vsebina, ne ponaredek.

V tem je celoten smisel: skripta reciklažnega obrata ne potrebuje odjemalca, specifičnega za qr3. Izvede HTTP GET, razčleni JSON-LD, ki ga že razume, in neposredno prebere GTIN ter ime izdelka.

En URL, dve občinstvi: pogajanje o vsebini

Isti URL https://qr3.app/dpp/{gtin}/{serial} streže tako prijazen potni list HTML za ljudi kot strojni pogled — strežnik se odloči, kaj vrniti, glede na to, kaj zahteva klicatelj. Dva načina, kako zahtevati:

Kar želite Parameter poizvedbe Ali glava Accept
Stran HTML za ljudi (privzeto) Accept: text/html
JSON-LD (povezani podatki) ?format=jsonld Accept: application/ld+json
Navadni JSON ?format=json —
Linkset (povezani viri) ?format=linkset —
DCAT-AP (metapodatki nabora podatkov) ?format=dcat-ap —

Tako kamera telefona ob odprtju kode QR pristane na berljivem potnem listu HTML, medtem ko skripta od istega URL-ja zahteva application/ld+json in dobi strukturirane podatke:

# Strojni pogled prek pogajanja z glavo — isti URL, brez poizvedbenega niza
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

En identifikator, en URL, mnogo predstavitev. GTIN/serijska številka ostane stabilna; pogled se prilagodi klicatelju. Prav to naredi DPP hkrati trajen in interoperabilen.

Kam sodi EPCIS 2.0 (dogodki proti potnemu listu)

Pogosto naslednje vprašanje: kaj pa EPCIS — ali ni to standard GS1 za to? Pomembno razlikovanje:

  • DPP je statični opis enega izdelka — njegove identitete, materialov, ogljičnega odtisa, možnosti recikliranja. Odgovarja na vprašanje "kaj je ta stvar?" Zgornji JSON-LD je ta posnetek.
  • EPCIS 2.0 je standard GS1 za dogodke v dobavni verigi — podatke o vidljivosti glede tega, kaj se je zgodilo, kje, kdaj in zakaj: izdelek je bil zagnan v obtok, odpremljen, prejet, recikliran. Odgovarja na vprašanje "kaj se je s to stvarjo zgodilo in kje je?"

Sta dopolnilna, ne konkurenčna. Potni list vam pove, da je izdelek baterija s 5,2 kWh in 35 % recikliranega deleža; sled dogodkov EPCIS bi vam povedala, da je bila izdelana v Hamburgu na določen datum, odpremljena prek distribucijskega centra in prispela v reciklažni obrat. EPCIS 2.0 je tudi sam naklonjen JSON/JSON-LD, zato si oba delita isti pogled na svet povezanih podatkov in iste identifikatorje GS1 (GTIN + serijska številka) kot ključ za združevanje.

Obseg qr3 (bodimo natančni): qr3 izpiše DPP kot JSON-LD — prav to ta zapis prikazuje. qr3 ne zagotavlja zajema dogodkov EPCIS ali končnih točk EPCIS. EPCIS 2.0 tu obravnavajte kot konceptualni, dopolnilni standard, ki bi ga ob DPP prevzeli za popolno sledljivost v dobavni verigi, in ne kot funkcijo qr3.

Miselni model je torej: DPP (qr3, JSON-LD) je identifikacijski list izdelka; EPCIS 2.0 (ločen sistem) je njegov dnevnik poti. Isti identifikatorji, odgovor na dve vprašanji.

Ustvarjanje DPP-ja, ki izpostavi JSON-LD

Za "omogočanje" JSON-LD ni treba storiti ničesar posebnega — ustvarite potni list in razreševalnik samodejno streže vsako predstavitev:

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

Ko je ustvarjen, URL izdelka takoj odgovarja obema občinstvoma — brez dodatnega koraka objave za strojni pogled.

Pogosta vprašanja

Zakaj JSON-LD in ne navadni JSON? Navadni JSON je strukturiran, a ne samoopisen: uporabnik se mora naučiti vaših imen polj. JSON-LD doda @context, ki vsak ključ preslika v izraze schema.org / GS1, tako da ga vsak uporabnik povezanih podatkov razume brez integracije po meri. Če potrebujete le hiter zajem, je ?format=json še vedno na voljo.

Ali qr3 implementira EPCIS 2.0? Ne. qr3 izpiše DPP kot JSON-LD. EPCIS 2.0 je ločen, dopolnilni standard GS1 za dogodke v dobavni verigi; izvajali bi ga vzporedno, združenega prek skupnih GTIN + serijska številka.

Kako pridobim strojni pogled? URL-ju razreševalnika dodajte ?format=jsonld ali pošljite Accept: application/ld+json. Oba vrneta isto vsebino povezanih podatkov.

Ali je @context stabilen? Pripenja schema.org in spletni besednjak GS1 (gs1.org/voc/) — oba sta javna, verzionirana besednjaka, zato se uporabniki lahko zanesejo na pomene izrazov.

Viri

Začnite brezplačno in ustvarite DPP, ki izpostavi JSON-LD: app.qr3.app/sign-up

Povezani članki

← Vsi članki Ustvari brezplačno