JSON-LD per i Passaporti Digitali di Prodotto (e dove si colloca EPCIS 2.0)

Un Passaporto Digitale di Prodotto è pensato per essere letto dalle persone e dalle macchine: il sistema di conferimento di un riciclatore, un'API doganale, il crawler di un marketplace, lo script di un revisore della sostenibilità. Una pagina HTML pensata solo per gli esseri umani non basta. Il passaporto deve essere leggibile dalle macchine — un payload strutturato che un programma può analizzare, collegare ed elaborare logicamente senza ricorrere allo scraping.

Questa guida è rivolta agli sviluppatori che si pongono la domanda successiva più ovvia: una volta che ho un DPP, come fa concretamente una macchina a leggerlo? La risposta per qr3 è JSON-LD tramite il resolver pubblico. Mostreremo la risposta reale, spiegheremo come lo stesso URL serva gli esseri umani e le macchine, e poi collocheremo nel contesto EPCIS 2.0 — lo standard GS1 complementare per gli eventi.

Cosa significa leggibilità dalle macchine per un DPP

Leggibile dalle macchine è qualcosa di più che "restituisce JSON". Per un passaporto di prodotto significa tre cose:

Strutturato — campi che un parser può indirizzare (gtin, name, …), non testo discorsivo da sottoporre a scraping.
Tipizzato e collegato — termini ancorati a vocabolari condivisi, così che Product significhi la stessa cosa per tutti. È il Linked Data presente in JSON-LD.
Stabile da recuperare — un unico URL duraturo per ciascun articolo, su cui uno script può eseguire un GET per l'intero ciclo di vita del prodotto.

JSON-LD (JSON for Linking Data) garantisce tutti e tre gli aspetti. È normale JSON con in più un @context che mappa ogni chiave a un termine in un vocabolario pubblico — qui schema.org e il GS1 Web Vocabulary. Un crawler che già comprende schema.org comprende il passaporto senza alcuna integrazione personalizzata.

Il DPP come JSON-LD (curl reale + risposta verificata)

Ogni passaporto qr3 si risolve a un URL GS1 Digital Link: https://qr3.app/dpp/{gtin}/{serial}. Aggiungi ?format=jsonld per richiedere la vista Linked-Data. Sulla demo live della batteria:

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

restituisce:

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

Tre cose da notare:

@context è un array di due vocabolari — schema.org per il web generale e gs1.org/voc/ per i termini di prodotto di GS1. Le chiavi si risolvono rispetto a entrambi.
@type: "Product" indica a qualsiasi consumatore Linked-Data esattamente di che tipo di entità si tratta.
I valori (gtin, name) sono reali e live — questo è il payload effettivo, non un mock.

Questo è proprio il punto: lo script di un riciclatore non ha bisogno di un client specifico per qr3. Esegue un GET HTTP, analizza il JSON-LD che già comprende e legge direttamente il GTIN e il nome del prodotto.

Un URL, due pubblici: content negotiation

Lo stesso URL https://qr3.app/dpp/{gtin}/{serial} serve un passaporto HTML adatto agli esseri umani e la vista per le macchine — il server decide cosa restituire in base a ciò che il chiamante richiede. Due modi per richiederlo:

Cosa vuoi	Query param	Oppure header Accept
Pagina HTML per umani	(predefinito)	`Accept: text/html`
JSON-LD (Linked Data)	`?format=jsonld`	`Accept: application/ld+json`
JSON semplice	`?format=json`	—
Linkset (risorse correlate)	`?format=linkset`	—
DCAT-AP (metadati del dataset)	`?format=dcat-ap`	—

Così la fotocamera di uno smartphone che apre il QR atterra sul passaporto HTML leggibile, mentre uno script richiede all'URL identico il formato application/ld+json e ottiene dati strutturati:

# Vista per le macchine tramite negoziazione dell'header — stesso URL, nessuna query string
curl -s -H "Accept: application/ld+json" \
  "https://qr3.app/dpp/04019999999902/DEMO-BAT-01"

Un identificatore, un URL, molte rappresentazioni. Il GTIN/serial resta stabile; la vista si adatta al chiamante. È esattamente ciò che rende un DPP al tempo stesso duraturo e interoperabile.

Dove si colloca EPCIS 2.0 (eventi vs. passaporto)

Una domanda frequente che ne consegue: e EPCIS — non è quello lo standard GS1 per questo? Distinzione importante:

Un DPP è la descrizione statica di un singolo articolo di prodotto — la sua identità, i materiali, l'impronta di carbonio, la riciclabilità. Risponde alla domanda "che cos'è questa cosa?" Il JSON-LD qui sopra è proprio quell'istantanea.
EPCIS 2.0 è lo standard GS1 per gli eventi della supply chain — i dati di visibilità su cosa è successo, dove, quando e perché: un articolo è stato commissionato, spedito, ricevuto, riciclato. Risponde alla domanda "cosa è successo a questa cosa e dove si trova?"

Sono complementari, non in concorrenza. Il passaporto ti dice che il prodotto è una batteria da 5,2 kWh con il 35% di contenuto riciclato; una traccia di eventi EPCIS ti direbbe che è stata fabbricata ad Amburgo in una certa data, spedita attraverso un centro di distribuzione e arrivata da un riciclatore. EPCIS 2.0 è esso stesso compatibile con JSON/JSON-LD, perciò i due condividono la stessa visione Linked-Data e gli stessi identificatori GS1 (GTIN + serial) come chiave di join.

Ambito di qr3 (sii preciso): qr3 produce in output il DPP come JSON-LD — è ciò che questo articolo dimostra. qr3 non fornisce la cattura di eventi EPCIS né endpoint EPCIS. Considera qui EPCIS 2.0 come lo standard concettuale e complementare che adotteresti accanto a un DPP per una tracciabilità completa della supply chain, non come una funzionalità di qr3.

Il modello mentale, quindi, è questo: il DPP (qr3, JSON-LD) è la scheda di identità del prodotto; EPCIS 2.0 (sistema separato) è il suo registro di viaggio. Stessi identificatori, due domande a cui si risponde.

Generare un DPP che espone JSON-LD

Non devi fare nulla di speciale per "abilitare" JSON-LD — crea il passaporto e il resolver serve automaticamente ogni rappresentazione:

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

// Il passaporto ora si risolve a https://qr3.app/dpp/04019999999902/SN-00012345
// Gli umani ottengono HTML; le macchine aggiungono ?format=jsonld (oppure inviano Accept: application/ld+json).
console.log(passport.qr.svg); // Il QR codifica il GS1 Digital Link verso il resolver

Una volta creato, l'URL dell'articolo risponde immediatamente a entrambi i pubblici — nessun passaggio di pubblicazione aggiuntivo per la vista delle macchine.

FAQ

Perché JSON-LD e non JSON semplice? Il JSON semplice è strutturato ma non autodescrittivo: un consumatore deve imparare i nomi dei tuoi campi. JSON-LD aggiunge @context, mappando ogni chiave ai termini di schema.org / GS1, così che qualsiasi consumatore Linked-Data lo comprenda senza un'integrazione personalizzata. Se ti serve solo una lettura veloce, ?format=json resta comunque disponibile.

qr3 implementa EPCIS 2.0? No. qr3 produce in output il DPP come JSON-LD. EPCIS 2.0 è lo standard GS1 separato e complementare per gli eventi della supply chain; lo eseguiresti in parallelo, unito tramite il GTIN + serial condivisi.

Come ottengo la vista per le macchine? Aggiungi ?format=jsonld all'URL del resolver, oppure invia Accept: application/ld+json. Entrambi restituiscono lo stesso payload Linked-Data.

Il @context è stabile? Fissa schema.org più il GS1 Web Vocabulary (gs1.org/voc/) — entrambi vocabolari pubblici e versionati, così i consumatori possono fare affidamento sul significato dei termini.

Fonti

Inizia gratis e crea un DPP che espone JSON-LD: app.qr3.app/sign-up