JSON-LD pro digitální produktové pasy (a kam zapadá EPCIS 2.0)

Digitální produktový pas má číst lidé i stroje: příjmový systém recyklátora, celní API, crawler tržiště, skript auditora udržitelnosti. HTML stránka určená pouze pro lidi nestačí. Pas musí být strojově čitelný — strukturovaná data, která program dokáže analyzovat, propojit a vyvozovat z nich závěry bez scrapování.

Tento průvodce je pro vývojáře, kteří si kladou nasnadě další otázku: jakmile mám DPP, jak ho stroj vlastně přečte? Odpovědí pro qr3 je JSON-LD přes veřejný resolver. Ukážeme skutečnou odpověď, vysvětlíme, jak tatáž URL obsluhuje lidi i stroje, a poté zasadíme do kontextu EPCIS 2.0 — doplňkový standard událostí GS1.

Co znamená strojová čitelnost pro DPP

Strojová čitelnost je víc než „vrací JSON". U produktového pasu znamená tři věci:

Strukturovaný — pole, na která se parser dokáže odkázat (gtin, name, …), nikoli text k scrapování.
Typovaný a propojený — termíny ukotvené ve sdílených slovnících, aby Product znamenal pro všechny totéž. To je ono Linked Data v JSON-LD.
Stabilní pro načtení — jedna trvalá URL na položku, na kterou skript může po celou dobu životnosti produktu posílat GET.

JSON-LD (JSON for Linking Data) zajišťuje všechny tři. Je to obyčejné JSON plus @context, které mapuje každý klíč na termín ve veřejném slovníku — zde schema.org a GS1 Web Vocabulary. Crawler, který už rozumí schema.org, rozumí pasu bez jakékoli vlastní integrace.

DPP jako JSON-LD (skutečný curl + ověřená odpověď)

Každý pas qr3 se rozkládá na URL GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Přidáním ?format=jsonld si vyžádáte pohled Linked Data. Proti živému demu baterie:

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

vrátí:

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

Tři věci, kterých si je třeba povšimnout:

@context je pole dvou slovníků — schema.org pro obecný web a gs1.org/voc/ pro produktové termíny GS1. Klíče se rozkládají vůči oběma.
@type: "Product" říká kterémukoli konzumentovi Linked Data přesně, o jaký druh entity jde.
Hodnoty (gtin, name) jsou skutečné a živé — toto je reálná data, nikoli atrapa.

V tom je celý smysl: skript recyklátora nepotřebuje klienta specifického pro qr3. Provede HTTP GET, naparsuje JSON-LD, kterému už rozumí, a přečte GTIN a název produktu rovnou.

Jedna URL, dvě publika: obsahová negociace

Tatáž URL https://qr3.app/dpp/{gtin}/{serial} obsluhuje pro lidi přívětivý HTML pas i strojový pohled — server rozhoduje, co vrátí, podle toho, co volající požaduje. Dva způsoby, jak se zeptat:

Co chcete	Parametr dotazu	Nebo hlavička Accept
HTML stránka pro lidi	(výchozí)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Prosté JSON	`?format=json`	—
Linkset (související zdroje)	`?format=linkset`	—
DCAT-AP (metadata datové sady)	`?format=dcat-ap`	—

Takže kamera telefonu, která otevře QR, přistane na čitelném HTML pasu, zatímco skript se identické URL zeptá na application/ld+json a dostane strukturovaná data:

# Strojový pohled přes negociaci hlavičkou — stejná URL, žádný řetězec dotazu
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Jeden identifikátor, jedna URL, mnoho reprezentací. GTIN/sériové číslo zůstává stabilní; pohled se přizpůsobuje volajícímu. Přesně to dělá DPP trvalým a interoperabilním zároveň.

Kam zapadá EPCIS 2.0 (události vs. pas)

Častá navazující otázka: a co EPCIS — není to standard GS1 právě na tohle? Důležité rozlišení:

DPP je statický popis jedné produktové položky — její identita, materiály, uhlíková stopa, recyklovatelnost. Odpovídá na otázku „co je tato věc?" Výše uvedené JSON-LD je tento snímek.
EPCIS 2.0 je standard GS1 pro události dodavatelského řetězce — data o viditelnosti toho, co se stalo, kde, kdy a proč: položka byla uvedena do oběhu, odeslána, přijata, recyklována. Odpovídá na otázku „co se s touto věcí stalo a kde je?"

Jsou doplňkové, nikoli konkurenční. Pas vám řekne, že produkt je baterie o kapacitě 5,2 kWh s 35 % recyklovaného obsahu; stopa událostí EPCIS by vám řekla, že byla vyrobena v Hamburku v daný den, odeslána přes distribuční centrum a dorazila k recyklátorovi. Samotné EPCIS 2.0 je přívětivé k JSON/JSON-LD, takže oba sdílejí stejný pohled na svět Linked Data a stejné identifikátory GS1 (GTIN + sériové číslo) jako spojovací klíč.

Rozsah qr3 (buďte přesní): qr3 vydává DPP jako JSON-LD — to je to, co tento příspěvek demonstruje. qr3 neposkytuje zachytávání událostí EPCIS ani endpointy EPCIS. Berte zde EPCIS 2.0 jako konceptuální, doplňkový standard, který byste si k DPP osvojili pro plnou vysledovatelnost dodavatelského řetězce, nikoli jako funkci qr3.

Mentální model je tedy takový: DPP (qr3, JSON-LD) je identifikační list produktu; EPCIS 2.0 (samostatný systém) je jeho cestovní deník. Stejné identifikátory, dvě zodpovězené otázky.

Generování DPP, které zpřístupňuje JSON-LD

Pro „povolení" JSON-LD neděláte nic zvláštního — vytvoříte pas a resolver automaticky obsluhuje každou reprezentaci:

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

Po vytvoření URL položky okamžitě odpovídá oběma publikům — žádný další publikační krok pro strojový pohled.

Časté dotazy

Proč JSON-LD a ne prosté JSON? Prosté JSON je strukturované, ale ne sebepopisné: konzument se musí naučit vaše názvy polí. JSON-LD přidává @context, které mapuje každý klíč na termíny schema.org / GS1, takže mu kterýkoli konzument Linked Data rozumí bez vlastní integrace. Pokud potřebujete jen rychlé přečtení, ?format=json je stále k dispozici.

Implementuje qr3 EPCIS 2.0? Ne. qr3 vydává DPP jako JSON-LD. EPCIS 2.0 je samostatný, doplňkový standard GS1 pro události dodavatelského řetězce; spustili byste ho vedle, propojený sdíleným GTIN + sériovým číslem.

Jak získám strojový pohled? Připojte ?format=jsonld k URL resolveru, nebo pošlete Accept: application/ld+json. Obojí vrací stejná data Linked Data.

Je @context stabilní? Zafixovává schema.org plus GS1 Web Vocabulary (gs1.org/voc/) — oba jsou veřejné, verzované slovníky, takže se konzumenti mohou spolehnout na významy termínů.

Zdroje

Začněte zdarma a vytvořte DPP, které zpřístupňuje JSON-LD: app.qr3.app/sign-up