JSON-LD pre digitálne produktové pasy (a kam zapadá EPCIS 2.0)

Digitálny produktový pas má čítať človek aj stroj: príjmový systém recyklátora, colné API, crawler trhoviska, skript audítora udržateľnosti. HTML stránka určená len pre ľudí na to nestačí. Pas musí byť strojovo čitateľný — štruktúrovaný obsah, ktorý dokáže program spracovať, prepojiť a vyhodnotiť bez scrapovania.

Tento návod je pre vývojárov, ktorí si kladú zrejmú ďalšiu otázku: keď už mám DPP, ako ho stroj vlastne prečíta? Odpoveďou pre qr3 je JSON-LD cez verejný resolver. Ukážeme skutočnú odpoveď, vysvetlíme, ako tá istá URL obsluhuje ľudí aj stroje, a potom zasadíme do kontextu EPCIS 2.0 — doplnkový štandard udalostí od GS1.

Čo znamená strojová čitateľnosť pre DPP

Strojová čitateľnosť je viac než „vracia JSON". Pre produktový pas znamená tri veci:

Štruktúrovaný — polia, ktoré parser dokáže adresovať (gtin, name, …), nie próza na scrapovanie.
Typovaný a prepojený — termíny ukotvené v spoločných slovníkoch, aby Product znamenal pre všetkých to isté. To je tá Linked Data v JSON-LD.
Stabilne dostupný — jedna trvalá URL adresa na položku, ktorú skript dokáže GET-núť počas celého života produktu.

JSON-LD (JSON for Linking Data) prináša všetky tri vlastnosti. Je to bežný JSON plus @context, ktorý mapuje každý kľúč na termín vo verejnom slovníku — tu na schema.org a GS1 Web Vocabulary. Crawler, ktorý už rozumie schema.org, rozumie pasu bez akejkoľvek vlastnej integrácie.

DPP ako JSON-LD (skutočný curl + overená odpoveď)

Každý pas qr3 sa resolvuje na URL adrese GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Pridaním ?format=jsonld požiadate o zobrazenie v podobe Linked Data. Proti živému demu batérie:

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

vráti:

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

Tri veci, ktoré si treba všimnúť:

@context je pole dvoch slovníkov — schema.org pre všeobecný web a gs1.org/voc/ pre produktové termíny GS1. Kľúče sa resolvujú voči obom.
@type: "Product" ktorémukoľvek konzumentovi Linked Data presne hovorí, o aký druh entity ide.
Hodnoty (gtin, name) sú skutočné a živé — toto je reálny obsah odpovede, nie maketa.

O to presne ide: skript recyklátora nepotrebuje klienta špecifického pre qr3. Vykoná HTTP GET, naparsuje JSON-LD, ktorému už rozumie, a priamo z neho prečíta GTIN a názov produktu.

Jedna URL, dve publiká: obsahová negociácia

Tá istá URL adresa https://qr3.app/dpp/{gtin}/{serial} obsluhuje pas v podobe ľudsky prívetivého HTML aj strojové zobrazenie — server sa rozhodne, čo vráti, podľa toho, o čo volajúci požiada. Požiadať možno dvoma spôsobmi:

Čo chcete	Query parameter	Alebo Accept hlavička
Ľudská HTML stránka	(predvolené)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Obyčajný JSON	`?format=json`	—
Linkset (súvisiace zdroje)	`?format=linkset`	—
DCAT-AP (metadáta datasetu)	`?format=dcat-ap`	—

Takže kamera telefónu, ktorá otvorí QR kód, sa dostane na čitateľný HTML pas, zatiaľ čo skript požiada identickú URL o application/ld+json a dostane štruktúrované dáta:

# Strojové zobrazenie cez negociáciu hlavičkou — tá istá URL, žiadny query reťazec
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Jeden identifikátor, jedna URL, mnoho reprezentácií. GTIN/sériové číslo zostáva stabilné; zobrazenie sa prispôsobí volajúcemu. Práve to robí DPP súčasne trvalým aj interoperabilným.

Kam zapadá EPCIS 2.0 (udalosti vs. pas)

Častá doplňujúca otázka: čo EPCIS — nie je to ten štandard GS1 práve na toto? Dôležité rozlíšenie:

DPP je statický opis jednej produktovej položky — jej identita, materiály, uhlíková stopa, recyklovateľnosť. Odpovedá na otázku „čo je táto vec?" JSON-LD vyššie je práve táto momentka.
EPCIS 2.0 je štandard GS1 pre udalosti dodávateľského reťazca — dáta o viditeľnosti toho, čo sa stalo, kde, kedy a prečo: položka bola uvedená do obehu, odoslaná, prijatá, recyklovaná. Odpovedá na otázku „čo sa s touto vecou stalo a kde je?"

Sú doplnkové, nie konkurenčné. Pas vám povie, že produkt je 5,2 kWh batéria s 35 % recyklovaného obsahu; stopa udalostí EPCIS by vám povedala, že bola vyrobená v Hamburgu k danému dátumu, prešla cez distribučné centrum a dorazila k recyklátorovi. EPCIS 2.0 je sám o sebe priateľský k JSON/JSON-LD, takže oba zdieľajú ten istý pohľad na svet Linked Data a tie isté identifikátory GS1 (GTIN + sériové číslo) ako spojovací kľúč.

Rozsah qr3 (buďme presní): qr3 vydáva DPP ako JSON-LD — to je to, čo tento článok predvádza. qr3 neposkytuje zachytávanie udalostí EPCIS ani EPCIS endpointy. EPCIS 2.0 tu vnímajte ako koncepčný, doplnkový štandard, ktorý by ste prijali popri DPP pre úplnú sledovateľnosť dodávateľského reťazca, nie ako funkciu qr3.

Mentálny model je teda takýto: DPP (qr3, JSON-LD) je identifikačný list produktu; EPCIS 2.0 (samostatný systém) je jeho cestovný denník. Tie isté identifikátory, dve zodpovedané otázky.

Vytvorenie DPP, ktorý sprístupňuje JSON-LD

Nemusíte robiť nič zvláštne na „zapnutie" JSON-LD — vytvorte pas a resolver bude automaticky obsluhovať každú reprezentáciu:

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,
  },
});

// Pas sa teraz resolvuje na https://qr3.app/dpp/04019999999902/SN-00012345
// Ľudia dostanú HTML; stroje pripoja ?format=jsonld (alebo pošlú Accept: application/ld+json).
console.log(passport.qr.svg); // QR kóduje GS1 Digital Link na resolver

Po vytvorení URL položky obslúži obe publiká okamžite — pre strojové zobrazenie nie je potrebný žiadny ďalší publikačný krok.

Často kladené otázky

Prečo JSON-LD a nie obyčajný JSON? Obyčajný JSON je štruktúrovaný, ale nie samopopisný: konzument sa musí naučiť vaše názvy polí. JSON-LD pridáva @context, ktorý mapuje každý kľúč na termíny schema.org / GS1, takže mu ktorýkoľvek konzument Linked Data rozumie bez vlastnej integrácie. Ak potrebujete len rýchle prečítanie, ?format=json je stále k dispozícii.

Implementuje qr3 EPCIS 2.0? Nie. qr3 vydáva DPP ako JSON-LD. EPCIS 2.0 je samostatný, doplnkový štandard GS1 pre udalosti dodávateľského reťazca; spustili by ste ho popri, prepojený zdieľaným GTIN + sériovým číslom.

Ako získam strojové zobrazenie? K URL adrese resolvera pripojte ?format=jsonld alebo pošlite Accept: application/ld+json. Oba vrátia ten istý obsah Linked Data.

Je @context stabilný? Pripína schema.org plus GS1 Web Vocabulary (gs1.org/voc/) — oba sú verejné, verziované slovníky, takže konzumenti sa môžu spoľahnúť na význam termínov.

Zdroje

Začnite zadarmo a vytvorte DPP, ktorý sprístupňuje JSON-LD: app.qr3.app/sign-up