JSON-LD digitālajām produktu pasēm (un kur iederas EPCIS 2.0)

Digitālā produktu pase ir paredzēta lasīšanai gan cilvēkiem, gan mašīnām: pārstrādātāja pieņemšanas sistēmai, muitas API, tirgus laukuma rāpuļprogrammai, ilgtspējas auditora skriptam. Tikai cilvēkiem paredzēta HTML lapa ar to netiek galā. Pasei jābūt mašīnlasāmai — strukturētai datu kravai, ko programma var parsēt, sasaistīt un par to spriest bez izšķiršanas (scraping).

Šī rokasgrāmata ir paredzēta izstrādātājiem, kuri uzdod acīmredzamo nākamo jautājumu: kad man ir DPP, kā mašīna to patiešām nolasa? Atbilde qr3 gadījumā ir JSON-LD caur publisko atrisinātāju. Mēs parādīsim īsto atbildi, paskaidrosim, kā viens un tas pats URL apkalpo cilvēkus un mašīnas, un tad ievietosim kontekstā EPCIS 2.0 — papildinošo GS1 notikumu standartu.

Ko DPP gadījumā nozīmē mašīnlasāmība

Mašīnlasāmība ir kas vairāk par "atgriež JSON". Produktu pasei tā nozīmē trīs lietas:

Strukturēta — lauki, ko parsētājs var adresēt (gtin, name, …), nevis proza, kas jāizšķir.
Tipizēta un sasaistīta — termini, kas piesaistīti kopīgām vārdnīcām, lai Product ikvienam nozīmētu vienu un to pašu. Tieši tas ir sasaistītie dati (Linked Data) JSON-LD formātā.
Stabila atgūšanai — viens noturīgs URL katram vienumam, ko skripts var izsaukt ar GET visu produkta dzīves laiku.

JSON-LD (JSON for Linking Data) nodrošina visus trīs. Tas ir parasts JSON plus @context, kas katru atslēgu sasaista ar terminu publiskā vārdnīcā — šeit schema.org un GS1 tīmekļa vārdnīcā. Rāpuļprogramma, kas jau saprot schema.org, saprot pasi bez jebkādas pielāgotas integrācijas.

DPP kā JSON-LD (īsta curl + pārbaudīta atbilde)

Katra qr3 pase atrisinās GS1 Digital Link URL: https://qr3.app/dpp/{gtin}/{serial}. Pievieno ?format=jsonld, lai pieprasītu sasaistīto datu skatu. Pret dzīvo akumulatora demonstrāciju:

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

atgriež:

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

Trīs lietas, kam pievērst uzmanību:

@context ir divu vārdnīcu masīvs — schema.org vispārējam tīmeklim un gs1.org/voc/ GS1 produktu terminiem. Atslēgas atrisinās pret abām.
@type: "Product" jebkuram sasaistīto datu patērētājam precīzi norāda, kāda veida entītija tā ir.
Vērtības (gtin, name) ir īstas un dzīvas — šī ir faktiskā datu krava, nevis makets.

Tāda ir visa būtība: pārstrādātāja skriptam nav vajadzīgs qr3 specifisks klients. Tas veic HTTP GET, parsē JSON-LD, ko jau saprot, un nolasa GTIN un produkta nosaukumu tieši.

Viens URL, divas auditorijas: satura saskaņošana

Tas pats https://qr3.app/dpp/{gtin}/{serial} URL apkalpo gan cilvēkam draudzīgu HTML pasi, gan mašīnas skatu — serveris izlemj, ko atgriezt, atkarībā no tā, ko pieprasa izsaucējs. Divi veidi, kā pieprasīt:

Ko tu vēlies	Vaicājuma parametrs	Vai Accept galvene
Cilvēkam paredzēta HTML lapa	(noklusējums)	`Accept: text/html`
JSON-LD (sasaistītie dati)	`?format=jsonld`	`Accept: application/ld+json`
Vienkāršs JSON	`?format=json`	—
Linkset (saistītie resursi)	`?format=linkset`	—
DCAT-AP (datu kopas metadati)	`?format=dcat-ap`	—

Tātad tālruņa kamera, kas atver QR kodu, nonāk lasāmajā HTML pasē, kamēr skripts pieprasa identisko URL ar application/ld+json un saņem strukturētus datus:

# Machine view via header negotiation — same URL, no query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Viens identifikators, viens URL, daudzi attēlojumi. GTIN/sērijas numurs paliek stabils; skats pielāgojas izsaucējam. Tieši tas vienlaikus padara DPP noturīgu un sadarbspējīgu.

Kur iederas EPCIS 2.0 (notikumi pretstatā pasei)

Bieži sastopams turpinājuma jautājums: kā ar EPCIS — vai tas nav GS1 standarts šim nolūkam? Svarīga atšķirība:

DPP ir viena produkta vienuma statiskais apraksts — tā identitāte, materiāli, oglekļa pēda, pārstrādājamība. Tas atbild uz jautājumu "kas šī lieta ir?" Iepriekš redzamais JSON-LD ir šis momentuzņēmums.
EPCIS 2.0 ir GS1 standarts piegādes ķēdes notikumiem — redzamības datiem par to, kas notika, kur, kad un kāpēc: vienums tika nodots ekspluatācijā, nosūtīts, saņemts, pārstrādāts. Tas atbild uz jautājumu "kas ar šo lietu notika un kur tā atrodas?"

Tie ir papildinoši, nevis konkurējoši. Pase pateic, ka produkts ir 5,2 kWh akumulators ar 35% pārstrādāta satura; EPCIS notikumu pēdas pateiktu, ka tas tika izgatavots Hamburgā noteiktā datumā, nosūtīts caur izplatīšanas centru un nonācis pie pārstrādātāja. Pats EPCIS 2.0 ir draudzīgs JSON/JSON-LD formātam, tāpēc abi dala vienu un to pašu sasaistīto datu pasaules redzējumu un vienus un tos pašus GS1 identifikatorus (GTIN + sērijas numurs) kā savienošanas atslēgu.

qr3 tvērums (esi precīzs): qr3 atklāj DPP kā JSON-LD — tieši to šī ziņa demonstrē. qr3 nenodrošina EPCIS notikumu uztveršanu vai EPCIS galapunktus. Uztver EPCIS 2.0 šeit kā konceptuālo, papildinošo standartu, ko tu pieņemtu līdzās DPP pilnīgai piegādes ķēdes izsekojamībai, nevis kā qr3 funkciju.

Tātad domāšanas modelis ir šāds: DPP (qr3, JSON-LD) ir produkta identitātes lapa; EPCIS 2.0 (atsevišķa sistēma) ir tā ceļojumu žurnāls. Vieni un tie paši identifikatori, atbildes uz diviem jautājumiem.

DPP ģenerēšana, kas atklāj JSON-LD

Tev nekas īpašs nav jādara, lai "iespējotu" JSON-LD — izveido pasi, un atrisinātājs automātiski apkalpo katru attēlojumu:

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

Kad pase ir izveidota, vienuma URL nekavējoties atbild abām auditorijām — mašīnas skatam nav nepieciešams papildu publicēšanas solis.

Biežāk uzdotie jautājumi

Kāpēc JSON-LD, nevis vienkāršs JSON? Vienkāršs JSON ir strukturēts, bet ne pašaprakstošs: patērētājam ir jāapgūst tavi lauku nosaukumi. JSON-LD pievieno @context, sasaistot katru atslēgu ar schema.org / GS1 terminiem, tāpēc jebkurš sasaistīto datu patērētājs to saprot bez pielāgotas integrācijas. Ja tev vajadzīgs tikai ātrs nolasījums, joprojām ir pieejams ?format=json.

Vai qr3 ievieš EPCIS 2.0? Nē. qr3 atklāj DPP kā JSON-LD. EPCIS 2.0 ir atsevišķs, papildinošs GS1 standarts piegādes ķēdes notikumiem; to darbinātu līdzās, savienojot ar kopīgo GTIN + sērijas numuru.

Kā iegūt mašīnas skatu? Pievieno ?format=jsonld atrisinātāja URL vai nosūti Accept: application/ld+json. Abi atgriež vienu un to pašu sasaistīto datu kravu.

Vai @context ir stabils? Tas piesaista schema.org plus GS1 tīmekļa vārdnīcu (gs1.org/voc/) — abas ir publiskas, versionētas vārdnīcas, tāpēc patērētāji var paļauties uz terminu nozīmēm.

Avoti

Sāc bez maksas un izveido DPP, kas atklāj JSON-LD: app.qr3.app/sign-up