JSON-LD dla cyfrowych paszportów produktu (i miejsce EPCIS 2.0)

Cyfrowy paszport produktu ma być odczytywany przez ludzi oraz przez maszyny: system przyjęcia w zakładzie recyklingu, API celne, robot indeksujący platformy handlowej, skrypt audytora zrównoważonego rozwoju. Strona HTML przeznaczona wyłącznie dla ludzi to za mało. Paszport musi być odczytywalny maszynowo — uporządkowanym ładunkiem danych, który program może sparsować, połączyć i przetworzyć logicznie bez scrapowania.

Ten przewodnik jest skierowany do programistów zadających oczywiste kolejne pytanie: skoro mam już DPP, jak maszyna faktycznie go odczytuje? Odpowiedzią w przypadku qr3 jest JSON-LD udostępniany przez publiczny resolver. Pokażemy prawdziwą odpowiedź, wyjaśnimy, jak ten sam URL obsługuje ludzi i maszyny, a następnie umieścimy w kontekście EPCIS 2.0 — uzupełniający standard zdarzeń GS1.

Co odczytywalność maszynowa oznacza dla DPP

Odczytywalność maszynowa to coś więcej niż „zwraca JSON”. W przypadku paszportu produktu oznacza ona trzy rzeczy:

Uporządkowanie — pola, do których parser może się odwołać (gtin, name, …), a nie proza do scrapowania.
Typowanie i połączenie — terminy zakotwiczone we wspólnych słownikach, tak aby Product oznaczał to samo dla wszystkich. To właśnie Linked Data w JSON-LD.
Stabilność pobierania — jeden trwały URL na każdy egzemplarz, który skrypt może GET-ować przez całe życie produktu.

JSON-LD (JSON for Linking Data) zapewnia wszystkie trzy. To zwykły JSON wzbogacony o @context, który mapuje każdy klucz na termin z publicznego słownika — tutaj schema.org oraz GS1 Web Vocabulary. Robot indeksujący, który już rozumie schema.org, rozumie paszport bez żadnej niestandardowej integracji.

DPP jako JSON-LD (prawdziwy curl + zweryfikowana odpowiedź)

Każdy paszport qr3 rozwiązuje się pod adresem URL w formacie GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Dodaj ?format=jsonld, aby poprosić o widok Linked Data. Dla działającego demo baterii:

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

zwraca:

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

Trzy rzeczy warte uwagi:

@context to tablica dwóch słowników — schema.org dla ogólnego internetu oraz gs1.org/voc/ dla terminów produktowych GS1. Klucze rozwiązują się względem obu.
@type: "Product" mówi każdemu konsumentowi Linked Data dokładnie, jakiego rodzaju jest to encja.
Wartości (gtin, name) są prawdziwe i aktualne — to rzeczywisty ładunek danych, a nie atrapa.

O to właśnie chodzi: skrypt zakładu recyklingu nie potrzebuje klienta specyficznego dla qr3. Wykonuje żądanie HTTP GET, parsuje JSON-LD, który już rozumie, i odczytuje GTIN oraz nazwę produktu wprost.

Jeden URL, dwie grupy odbiorców: negocjacja treści

Ten sam URL https://qr3.app/dpp/{gtin}/{serial} obsługuje przyjazny dla człowieka paszport HTML oraz widok maszynowy — serwer decyduje, co zwrócić, na podstawie tego, o co prosi wywołujący. Są dwa sposoby, by o to poprosić:

Czego chcesz	Parametr zapytania	Lub nagłówek Accept
Strona HTML dla człowieka	(domyślnie)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
Zwykły JSON	`?format=json`	—
Linkset (powiązane zasoby)	`?format=linkset`	—
DCAT-AP (metadane zbioru danych)	`?format=dcat-ap`	—

Tak więc aparat telefonu otwierający kod QR trafia na czytelny paszport HTML, podczas gdy skrypt prosi identyczny URL o application/ld+json i otrzymuje uporządkowane dane:

# Widok maszynowy przez negocjację nagłówkiem — ten sam URL, bez query stringu
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Jeden identyfikator, jeden URL, wiele reprezentacji. GTIN/numer seryjny pozostaje stabilny; widok dostosowuje się do wywołującego. To właśnie sprawia, że DPP jest jednocześnie trwały i interoperacyjny.

Gdzie pasuje EPCIS 2.0 (zdarzenia kontra paszport)

Częste kolejne pytanie: a co z EPCIS — czy to nie jest standard GS1 do tego? Ważne rozróżnienie:

DPP to statyczny opis jednego egzemplarza produktu — jego tożsamość, materiały, ślad węglowy, możliwość recyklingu. Odpowiada na pytanie „czym jest ta rzecz?”. Powyższy JSON-LD to właśnie ten zrzut.
EPCIS 2.0 to standard GS1 dla zdarzeń w łańcuchu dostaw — danych o widoczności dotyczących tego, co się stało, gdzie, kiedy i dlaczego: egzemplarz został wprowadzony do obrotu, wysłany, odebrany, poddany recyklingowi. Odpowiada na pytanie „co się stało z tą rzeczą i gdzie ona jest?”.

Są one komplementarne, nie konkurencyjne. Paszport mówi ci, że produkt to bateria o pojemności 5,2 kWh z 35% zawartości materiałów z recyklingu; ślad zdarzeń EPCIS powiedziałby ci, że została wyprodukowana w Hamburgu danego dnia, przewieziona przez centrum dystrybucyjne i dotarła do zakładu recyklingu. Sam EPCIS 2.0 jest przyjazny dla JSON/JSON-LD, więc oba dzielą tę samą wizję świata Linked Data oraz te same identyfikatory GS1 (GTIN + numer seryjny) jako klucz łączący.

Zakres qr3 (precyzyjnie): qr3 wystawia DPP jako JSON-LD — to właśnie demonstruje ten wpis. qr3 nie zapewnia przechwytywania zdarzeń EPCIS ani punktów końcowych EPCIS. Traktuj EPCIS 2.0 w tym kontekście jako koncepcyjny, uzupełniający standard, który przyjąłbyś obok DPP w celu pełnej identyfikowalności łańcucha dostaw, a nie jako funkcję qr3.

Tak więc model myślowy jest następujący: DPP (qr3, JSON-LD) to karta tożsamości produktu; EPCIS 2.0 (osobny system) to jego dziennik podróży. Te same identyfikatory, odpowiedzi na dwa pytania.

Generowanie DPP, który udostępnia JSON-LD

Nie robisz nic specjalnego, by „włączyć” JSON-LD — utwórz paszport, a resolver automatycznie serwuje każdą reprezentację:

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 utworzeniu URL egzemplarza natychmiast odpowiada obu grupom odbiorców — bez dodatkowego kroku publikacji dla widoku maszynowego.

FAQ

Dlaczego JSON-LD, a nie zwykły JSON? Zwykły JSON jest uporządkowany, ale nie samoopisujący się: konsument musi poznać nazwy twoich pól. JSON-LD dodaje @context, mapując każdy klucz na terminy schema.org / GS1, dzięki czemu każdy konsument Linked Data rozumie go bez niestandardowej integracji. Jeśli potrzebujesz tylko szybkiego odczytu, ?format=json jest nadal dostępny.

Czy qr3 implementuje EPCIS 2.0? Nie. qr3 wystawia DPP jako JSON-LD. EPCIS 2.0 to osobny, uzupełniający standard GS1 dla zdarzeń w łańcuchu dostaw; uruchomiłbyś go obok, połączony za pomocą wspólnego GTIN + numeru seryjnego.

Jak uzyskać widok maszynowy? Dołącz ?format=jsonld do adresu URL resolvera lub wyślij Accept: application/ld+json. Oba zwracają ten sam ładunek Linked Data.

Czy @context jest stabilny? Przypina on schema.org oraz GS1 Web Vocabulary (gs1.org/voc/) — oba publiczne, wersjonowane słowniki, dzięki czemu konsumenci mogą polegać na znaczeniu terminów.

Źródła

Zacznij za darmo i utwórz DPP udostępniający JSON-LD: app.qr3.app/sign-up