A digitális termékútlevél célja, hogy emberek és gépek egyaránt olvashassák: egy újrahasznosító üzem átvételi rendszere, egy vámügyi API, egy piactér-feltérképező robot, egy fenntarthatósági auditor szkriptje. Egy kizárólag emberek számára készült HTML-oldal nem elegendő. Az útlevélnek gépileg olvashatónak kell lennie — strukturált adatcsomagnak, amelyet egy program scraping nélkül képes feldolgozni, összekapcsolni és értelmezni.
Ez az útmutató azoknak a fejlesztőknek szól, akik a kézenfekvő következő kérdést teszik fel: ha már megvan a DPP-m, hogyan olvassa azt el ténylegesen egy gép? A válasz a qr3 esetében a nyilvános resolveren keresztül szolgáltatott JSON-LD. Megmutatjuk a valódi választ, elmagyarázzuk, hogyan szolgál ki ugyanaz az URL embereket és gépeket, majd kontextusba helyezzük az EPCIS 2.0-t — a kiegészítő GS1 eseményszabványt.
Mit jelent a gépi olvashatóság egy DPP esetében
A gépi olvashatóság több, mint hogy „JSON-t ad vissza". Egy termékútlevél esetében három dolgot jelent:
- Strukturált — olyan mezők, amelyeket egy értelmező közvetlenül megcímezhet (
gtin,name, …), nem pedig kinyerendő próza. - Tipizált és összekapcsolt — a fogalmak közös szótárakhoz vannak rögzítve, így a
Productmindenki számára ugyanazt jelenti. Ez a Linked Data a JSON-LD-ben. - Stabilan lekérhető — egyetlen tartós URL elemenként, amelyet egy szkript a termék teljes élettartama alatt
GET-tel lekérhet.
A JSON-LD (JSON for Linking Data) mindhármat biztosítja. Ez közönséges JSON, kiegészítve egy @context-tel, amely minden kulcsot egy nyilvános szótár fogalmához rendel — itt a schema.org-hoz és a GS1 Web Vocabulary-hoz. Egy feltérképező robot, amely már érti a schema.org-ot, mindenféle egyedi integráció nélkül megérti az útlevelet.
A DPP mint JSON-LD (valódi curl + ellenőrzött válasz)
Minden qr3 útlevél egy GS1 Digital Link URL-en érhető el: https://qr3.app/dpp/{gtin}/{serial}. A ?format=jsonld hozzáadásával kérheted a Linked Data nézetet. Az élő akkumulátor-demón:
curl -s "https://qr3.app/dpp/04019999999902/DEMO-BAT-01?format=jsonld"
a következőt adja vissza:
{
"@context": ["https://schema.org", "https://gs1.org/voc/"],
"@type": "Product",
"gtin": "04019999999902",
"name": "EcoMax 5000 (Demo)"
}
Három dolgot érdemes megjegyezni:
- A
@contextegy tömb, amely két szótárat tartalmaz — a schema.org-ot az általános webhez, és ags1.org/voc/-ot a GS1 termékfogalmaihoz. A kulcsok mindkettő alapján feloldhatók. - A
@type: "Product"bármely Linked Data fogyasztó számára pontosan megmondja, milyen típusú entitásról van szó. - Az értékek (
gtin,name) valódiak és élők — ez a tényleges adatcsomag, nem egy minta.
Pontosan ez a lényeg: egy újrahasznosító üzem szkriptjének nincs szüksége qr3-specifikus kliensre. Végrehajt egy HTTP GET-et, feldolgozza az általa már ismert JSON-LD-t, és közvetlenül kiolvassa a GTIN-t és a terméknevet.
Egy URL, két közönség: tartalom-egyeztetés
Ugyanaz a https://qr3.app/dpp/{gtin}/{serial} URL egyszerre szolgál ki egy ember számára barátságos HTML-útlevelet és a gépi nézetet — a szerver dönti el, mit ad vissza aszerint, hogy mit kér a hívó fél. Kétféleképpen kérheted:
| Amit szeretnél | Lekérdezési paraméter | Vagy Accept fejléc |
|---|---|---|
| Ember számára olvasható HTML-oldal | (alapértelmezett) | Accept: text/html |
| JSON-LD (Linked Data) | ?format=jsonld |
Accept: application/ld+json |
| Egyszerű JSON | ?format=json |
— |
| Linkset (kapcsolódó erőforrások) | ?format=linkset |
— |
| DCAT-AP (adatkészlet-metaadatok) | ?format=dcat-ap |
— |
Így egy telefonkamera, amely megnyitja a QR-kódot, az olvasható HTML-útlevélen köt ki, miközben egy szkript az azonos URL-től application/ld+json formátumot kér, és strukturált adatokat kap:
# Gépi nézet fejléc-egyeztetéssel — ugyanaz az URL, lekérdezési karakterlánc nélkül
curl -s -H "Accept: application/ld+json" \
"https://qr3.app/dpp/04019999999902/DEMO-BAT-01"
Egy azonosító, egy URL, sokféle reprezentáció. A GTIN/serial stabil marad; a nézet alkalmazkodik a hívó félhez. Pontosan ettől lesz egy DPP egyszerre tartós és interoperábilis.
Hol illeszkedik az EPCIS 2.0 (események kontra útlevél)
Gyakori következő kérdés: mi a helyzet az EPCIS-szel — nem az a GS1 szabvány erre? Fontos megkülönböztetés:
- A DPP egyetlen termékelem statikus leírása — annak azonossága, anyagai, szénlábnyoma, újrahasznosíthatósága. Arra a kérdésre válaszol, hogy „mi ez a dolog?" A fenti JSON-LD ez a pillanatkép.
- Az EPCIS 2.0 a GS1 szabványa az ellátási lánc eseményeire — a láthatósági adatokra arról, hogy mi történt, hol, mikor és miért: egy elemet legyártottak, kiszállítottak, átvettek, újrahasznosítottak. Arra a kérdésre válaszol, hogy „mi történt ezzel a dologgal, és hol van?"
Ezek kiegészítik egymást, nem versenyeznek. Az útlevél elárulja, hogy a termék egy 5,2 kWh-s akkumulátor 35% újrahasznosított tartalommal; egy EPCIS eseménynapló pedig azt, hogy egy adott napon Hamburgban gyártották, egy elosztóközponton keresztül szállították, és megérkezett egy újrahasznosítóhoz. Maga az EPCIS 2.0 JSON/JSON-LD-barát, így a kettő ugyanazt a Linked Data világképet és ugyanazokat a GS1 azonosítókat (GTIN + serial) használja összekapcsolási kulcsként.
qr3 hatókör (legyünk pontosak): a qr3 a DPP-t JSON-LD formátumban teszi közzé — ezt mutatja be ez a bejegyzés. A qr3 nem biztosít EPCIS eseményrögzítést vagy EPCIS végpontokat. Az EPCIS 2.0-t itt fogalmi, kiegészítő szabványként kezeld, amelyet a DPP mellett vezetnél be a teljes ellátásilánc-nyomonkövetéshez, nem pedig qr3 funkcióként.
A gondolati modell tehát a következő: a DPP (qr3, JSON-LD) a termék azonossági adatlapja; az EPCIS 2.0 (külön rendszer) a termék útinaplója. Ugyanazok az azonosítók, két megválaszolt kérdés.
JSON-LD-t közzétevő DPP létrehozása
Semmi különöset nem kell tenned a JSON-LD „engedélyezéséhez" — hozd létre az útlevelet, és a resolver minden reprezentációt automatikusan kiszolgál:
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,
},
});
// Az útlevél most a https://qr3.app/dpp/04019999999902/SN-00012345 címen érhető el
// Az emberek HTML-t kapnak; a gépek a ?format=jsonld-t fűzik hozzá (vagy Accept: application/ld+json fejlécet küldenek).
console.log(passport.qr.svg); // A QR a resolverhez vezető GS1 Digital Linket kódolja
A létrehozás után az elem URL-je azonnal mindkét közönséget kiszolgálja — nincs szükség külön közzétételi lépésre a gépi nézethez.
GYIK
Miért JSON-LD és nem egyszerű JSON?
Az egyszerű JSON strukturált, de nem önleíró: a fogyasztónak meg kell tanulnia a mezőneveidet. A JSON-LD hozzáadja az @context-et, amely minden kulcsot a schema.org / GS1 fogalmaihoz rendel, így bármely Linked Data fogyasztó megérti egyedi integráció nélkül. Ha csak gyors beolvasásra van szükséged, a ?format=json továbbra is elérhető.
Megvalósítja a qr3 az EPCIS 2.0-t? Nem. A qr3 a DPP-t JSON-LD formátumban teszi közzé. Az EPCIS 2.0 a külön, kiegészítő GS1 szabvány az ellátási lánc eseményeire; ezt mellette futtatnád, a közös GTIN + serial alapján összekapcsolva.
Hogyan kapom meg a gépi nézetet?
Fűzd hozzá a ?format=jsonld-t a resolver URL-jéhez, vagy küldj Accept: application/ld+json fejlécet. Mindkettő ugyanazt a Linked Data adatcsomagot adja vissza.
Stabil az @context?
A schema.org-ot és a GS1 Web Vocabularyt (gs1.org/voc/) rögzíti — mindkettő nyilvános, verziózott szótár, így a fogyasztók megbízhatnak a fogalmak jelentésében.
Források
- JSON-LD 1.1 (W3C Recommendation)
- GS1 Web Vocabulary
- GS1 EPCIS and CBV 2.0
- schema.org Product
- ESPR — Regulation (EU) 2024/1781
Kezdd el ingyen, és hozz létre egy JSON-LD-t közzétevő DPP-t: app.qr3.app/sign-up
