JSON-LD za digitalne putovnice proizvoda (i gdje se uklapa EPCIS 2.0)

Digitalna putovnica proizvoda namijenjena je tome da je čitaju ljudi i strojevi: prijemni sustav reciklažera, carinski API, indekser tržnice, skripta revizora održivosti. HTML stranica isključivo za ljude tu nije dovoljna. Putovnica mora biti strojno čitljiva — strukturirani sadržaj koji program može parsirati, povezati i nad njim zaključivati bez struganja (scrapinga).

Ovaj je vodič namijenjen razvojnim inženjerima koji postavljaju očito sljedeće pitanje: kad već imam DPP, kako ga stroj zapravo čita? Odgovor za qr3 je JSON-LD putem javnog resolvera. Pokazat ćemo stvarni odgovor, objasniti kako isti URL poslužuje ljude i strojeve, a zatim u kontekst staviti EPCIS 2.0 — komplementarni GS1 standard događaja.

Što za DPP znači strojna čitljivost

Strojna čitljivost više je od „vraća JSON". Za putovnicu proizvoda to znači troje:

Strukturirano — polja koja parser može adresirati (gtin, name, …), a ne proza koju treba strugati.
Tipizirano i povezano — pojmovi usidreni u zajedničke rječnike tako da Product svima znači isto. To je povezani podatak (Linked Data) u JSON-LD-u.
Stabilno za dohvat — jedan trajni URL po proizvodu nad kojim skripta može izvršiti GET tijekom cijelog životnog vijeka proizvoda.

JSON-LD (JSON for Linking Data) isporučuje svo troje. To je običan JSON uz @context koji svaki ključ preslikava u pojam iz javnog rječnika — ovdje schema.org i GS1 Web Vocabulary. Indekser koji već razumije schema.org razumije putovnicu bez ikakve prilagođene integracije.

DPP kao JSON-LD (stvarni curl + provjereni odgovor)

Svaka qr3 putovnica razrješava se na GS1 Digital Link URL-u: https://qr3.app/dpp/{gtin}/{serial}. Dodajte ?format=jsonld da biste zatražili prikaz u obliku povezanih podataka. Na živom demo primjeru baterije:

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

vraća:

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

Tri stvari koje treba uočiti:

@context je polje dvaju rječnika — schema.org za opći web i gs1.org/voc/ za GS1-ove pojmove o proizvodima. Ključevi se razrješavaju u oba.
@type: "Product" svakom potrošaču povezanih podataka točno govori o kojoj je vrsti entiteta riječ.
Vrijednosti (gtin, name) stvarne su i žive — ovo je stvarni sadržaj, a ne maketa.

U tome je cijela poanta: skripti reciklažera nije potreban klijent specifičan za qr3. Ona izvrši HTTP GET, parsira JSON-LD koji već razumije i izravno očita GTIN i naziv proizvoda.

Jedan URL, dvije publike: pregovaranje o sadržaju

Isti URL https://qr3.app/dpp/{gtin}/{serial} poslužuje i ljudima prilagođenu HTML putovnicu i strojni prikaz — poslužitelj odlučuje što vratiti na temelju onoga što pozivatelj zatraži. Dva su načina da se to zatraži:

Što želite	Parametar upita	Ili Accept zaglavlje
Ljudska HTML stranica	(zadano)	`Accept: text/html`
JSON-LD (povezani podaci)	`?format=jsonld`	`Accept: application/ld+json`
Običan JSON	`?format=json`	—
Linkset (povezani resursi)	`?format=linkset`	—
DCAT-AP (metapodaci skupa podataka)	`?format=dcat-ap`	—

Tako kamera telefona koja otvori QR slijeće na čitljivu HTML putovnicu, dok skripta od istog URL-a traži application/ld+json i dobiva strukturirane podatke:

# Strojni prikaz putem pregovaranja zaglavljem — isti URL, bez upitnog niza
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Jedan identifikator, jedan URL, mnogo prikaza. GTIN/serijski broj ostaje stabilan; prikaz se prilagođava pozivatelju. Upravo to istodobno čini DPP trajnim i interoperabilnim.

Gdje se uklapa EPCIS 2.0 (događaji nasuprot putovnici)

Uobičajeno popratno pitanje: a što je s EPCIS-om — nije li to GS1 standard za ovo? Važno je razlikovanje:

DPP je statički opis jednog primjerka proizvoda — njegov identitet, materijali, ugljični otisak, mogućnost recikliranja. Odgovara na pitanje „što je ova stvar?" JSON-LD iznad upravo je ta snimka stanja.
EPCIS 2.0 je GS1-ov standard za događaje u opskrbnom lancu — podatke o vidljivosti što se dogodilo, gdje, kad i zašto: proizvod je pušten u promet, otpremljen, zaprimljen, recikliran. Odgovara na pitanje „što se dogodilo s ovom stvari i gdje je ona?"

Oni su komplementarni, a ne konkurentski. Putovnica vam govori da je proizvod baterija od 5,2 kWh s 35 % recikliranog sadržaja; trag EPCIS događaja rekao bi vam da je proizvedena u Hamburgu određenog datuma, otpremljena kroz distribucijski centar i stigla do reciklažera. EPCIS 2.0 sâm je pogodan za JSON/JSON-LD, pa oba dijele isti pogled na svijet povezanih podataka i iste GS1 identifikatore (GTIN + serijski broj) kao ključ za povezivanje.

Opseg qr3 (budite precizni): qr3 izlaže DPP kao JSON-LD — to je ono što ova objava demonstrira. qr3 ne pruža bilježenje EPCIS događaja niti EPCIS pristupne točke. EPCIS 2.0 ovdje tretirajte kao konceptualni, komplementarni standard koji biste usvojili uz DPP radi potpune sljedivosti opskrbnog lanca, a ne kao značajku qr3.

Dakle, mentalni model je sljedeći: DPP (qr3, JSON-LD) jest identifikacijski list proizvoda; EPCIS 2.0 (zaseban sustav) jest njegov dnevnik putovanja. Isti identifikatori, dva odgovorena pitanja.

Generiranje DPP-a koji izlaže JSON-LD

Ne morate učiniti ništa posebno da biste „omogućili" JSON-LD — stvorite putovnicu i resolver automatski poslužuje svaki prikaz:

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

Nakon stvaranja, URL proizvoda odmah odgovara objema publikama — nema dodatnog koraka objave za strojni prikaz.

Česta pitanja

Zašto JSON-LD, a ne običan JSON? Običan JSON je strukturiran, ali nije samoopisujući: potrošač mora naučiti vaše nazive polja. JSON-LD dodaje @context koji svaki ključ preslikava u pojmove schema.org / GS1, pa ga svaki potrošač povezanih podataka razumije bez prilagođene integracije. Ako vam treba samo brzo očitavanje, ?format=json i dalje je dostupan.

Implementira li qr3 EPCIS 2.0? Ne. qr3 izlaže DPP kao JSON-LD. EPCIS 2.0 zaseban je, komplementarni GS1 standard za događaje u opskrbnom lancu; pokretali biste ga usporedno, povezanog zajedničkim GTIN-om + serijskim brojem.

Kako dobivam strojni prikaz? Dodajte ?format=jsonld na URL resolvera ili pošaljite Accept: application/ld+json. Oboje vraća isti sadržaj povezanih podataka.

Je li @context stabilan? On fiksira schema.org te GS1 Web Vocabulary (gs1.org/voc/) — oba su javni, verzionirani rječnici, pa se potrošači mogu osloniti na značenja pojmova.

Izvori

Započnite besplatno i izradite DPP koji izlaže JSON-LD: app.qr3.app/sign-up