Open Badge Baking spiegato: come il JSON vive dentro il PNG

Un Open Badge «baked» è un PNG con il JSON dell'asserzione incorporato come metadato dell'immagine. Il file del badge È la credenziale. Come funziona il baking e come verificare un badge baked.

Nacho Coll Di Aggiornato 12 min di lettura
Un Open Badge «baked» è un PNG con il JSON dell'asserzione incorporato come metadato dell'immagine. Il file del badge È la credenziale. Come funziona il baking e come verificare un badge baked.

Scarica un Open Badge da quasi qualsiasi emittente e otterrai un normalissimo PNG. Lo incolli in una chat, lo allegati a un’email, lo stampi. Sembra un’immagine come tante. Ma il file porta con sé un secondo livello, invisibile: la credenziale stessa, scritta nell’immagine come metadato. È ciò che la community Open Badges chiama badge baked, ed è il motivo per cui un badge può viaggiare come file singolo e dimostrare comunque chi l’ha emesso, a chi e per cosa.

Questa guida spiega cos’è il baking, dove vivono i dati dentro il file, come un verificatore li rilegge e che cosa devi decidere se emetti credenziali. Non serve scrivere codice per usare i badge baked. Se emetti tramite https://badges.ninja, il baking avviene per te. Ma capire i meccanismi ti aiuta a rispondere alle domande che destinatari e datori di lavoro pongono davvero: «Questa immagine è autentica?» e «Chiunque può semplicemente copiarla?»

Cosa significa «baking»

Un Open Badge ha due parti facili da confondere:

  • L’immagine. Il PNG o SVG che le persone vedono su un profilo, una slide o un certificato.
  • L’asserzione. Un piccolo documento JSON che enuncia i fatti: chi è il destinatario (come identificatore con hash), quale badge class è stata conseguita, chi l’ha emessa, quando e dove verificarla.

Il baking è l’atto di scrivere l’asserzione nell’immagine in modo che le due cose non possano essere separate. Il risultato è un solo file. Se passi a qualcuno il PNG, gli hai consegnato sia l’immagine sia l’affermazione che la sostiene.

L’idea nasce dalla specifica Open Badges, sviluppata originariamente da Mozilla e oggi mantenuta da 1EdTech. Il punto del design è la portabilità. All’inizio i badge vivevano dentro una singola piattaforma, e spostarne uno altrove significava ricaricarlo sperando che i metadati sopravvivessero. Un file baked porta i propri metadati ovunque vada.

Dove vive il JSON dentro un PNG

Un file PNG è una breve firma seguita da una sequenza di chunk. Ogni chunk ha una lunghezza, un tipo di quattro lettere, dei dati e un checksum. I visualizzatori disegnano i pixel dai chunk IDAT e ignorano i tipi di chunk che non capiscono. Questa tolleranza rende possibile il baking: puoi aggiungere un chunk pieno di testo e ogni visualizzatore al mondo mostrerà comunque l’immagine normalmente.

Per Open Badges 2.0, l’asserzione va in un chunk di testo con la parola chiave openbadges. I tipi di chunk di testo che possono contenerla sono:

ChunkCodificaNote
tEXtLatin-1Semplice, ma limitato ai caratteri Latin-1.
iTXtUTF-8Preferito, perché nomi e descrizioni spesso non sono ASCII.

Qualunque chunk si usi, lo schema è lo stesso: la parola chiave openbadges, un separatore, poi il payload. Il payload è una di due cose, a seconda di come l’emittente ha scelto di fare il baking:

  1. Il JSON dell’asserzione stesso. Il file è autodescrittivo. Un verificatore può leggere l’affermazione senza alcuna chiamata di rete.
  2. Un URL che punta all’asserzione ospitata. Il file è più piccolo e l’emittente può mantenere autorevole il record live, per esempio per mostrare che un badge è stato poi revocato o è scaduto.

Esiste una terza variante per i badge firmati, in cui il payload è un token firmato anziché JSON semplice. Se le firme contano per il tuo caso d’uso, leggi how to verify an Open Badge signature.

E per l’SVG?

Anche i badge SVG possono essere baked, dato che l’SVG è XML. L’asserzione viene inserita nel file in un elemento del namespace XML openbadges, e l’attributo verify contiene l’URL dell’asserzione ospitata. Il principio è lo stesso del PNG: i metadati viaggiano dentro il file immagine. In pratica la maggior parte delle piattaforme fa il baking in PNG, perché il PNG è accettato quasi ovunque si voglia caricare un badge.

Che aspetto ha l’asserzione incorporata

Per il formato 2.0, un’asserzione ospitata è JSON-LD che collega destinatario, badge class e metodo di verifica. Un esempio ridotto:

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://example.org/assertions/abc123",
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "deadsea",
    "identity": "sha256$c7ef86405ba71b85acd8e2e95166c4b111448089f2e1599f42fe1bba46e865c5"
  },
  "badge": "https://example.org/badges/data-analysis-101",
  "issuedOn": "2026-05-14T00:00:00Z",
  "verification": { "type": "hosted" }
}

Nota il destinatario. L’email non è memorizzata in chiaro: è un hash SHA-256 con salt. Conta, per un file pensato per circolare. Chiunque possieda il PNG può leggere l’asserzione, quindi l’asserzione non deve rivelare l’indirizzo del destinatario. Un verificatore che conosce già l’email può calcolarne l’hash con lo stesso salt e controllare che corrisponda. Per una guida campo per campo di questo documento, vedi il Open Badge JSON-LD walkthrough.

Come un verificatore legge un badge baked

La verifica di un badge baked è un processo breve e meccanico:

  1. Apri il PNG e scorri i suoi chunk.
  2. Trova il chunk di testo con la parola chiave openbadges.
  3. Leggi il payload. Se è JSON, fanne il parsing. Se è un URL, recuperalo.
  4. Controlla che l’asserzione si riferisca alla badge class e all’emittente che ti aspetti, e che l’identità del destinatario corrisponda alla persona che la presenta.
  5. Se il tipo di verifica è hosted, conferma che l’asserzione ospitata esista ancora al suo URL id e non sia stata revocata né sia scaduta.

Il punto 5 è quello che la gente salta, ed è quello che rende affidabile una credenziale. Una copia incorporata è un’istantanea. Il record ospitato è la fonte di verità.

Leggerlo da soli in Node

Puoi ispezionare qualsiasi PNG con un breve script. Questo scorre i chunk e stampa il payload openbadges, gestendo sia tEXt sia iTXt:

import { readFileSync } from "node:fs";
import { inflateSync } from "node:zlib";
const png = readFileSync(process.argv[2]);
let pos = 8; // skip the 8-byte PNG signature
while (pos < png.length) {
  const length = png.readUInt32BE(pos);
  const type = png.toString("ascii", pos + 4, pos + 8);
  const data = png.subarray(pos + 8, pos + 8 + length);
  if (type === "iTXt" || type === "tEXt") {
    const nul = data.indexOf(0);
    const keyword = data.toString("latin1", 0, nul);
    if (keyword === "openbadges") {
      let text;
      if (type === "tEXt") text = data.toString("latin1", nul + 1);
      else {
        const compressed = data[nul + 1] === 1;
        let p = nul + 3; // skip compression flag + method
        p = data.indexOf(0, p) + 1; // language tag
        p = data.indexOf(0, p) + 1; // translated keyword
        const body = data.subarray(p);
        text = (compressed ? inflateSync(body) : body).toString("utf8");
      }
      console.log(text);
      process.exit(0);
    }
  }
  pos += 12 + length; // length + type + data + CRC
}
console.error("No openbadges chunk found: this PNG is not baked.");
process.exit(1);

Eseguilo con node extract-badge.mjs my-badge.png. Se il file è baked vedrai JSON o un URL. Altrimenti ottieni un semplice messaggio «not baked». È uno strumento didattico, non un validatore completo: non controlla i checksum dei chunk, non analizza i payload firmati e non recupera il record ospitato.

Se preferisci non scrivere codice, un validatore di badge online o un visualizzatore di metadati PNG mostrerà lo stesso chunk. Il formato è lo standard, quindi qualsiasi strumento conforme legge qualsiasi badge conforme.

Perché il baking conta

Portabilità. Una credenziale che è solo un PNG può essere inviata via email, caricata su una piattaforma di apprendimento o conservata in un archivio personale. Non serve alcun account per portarla con sé.

Un percorso di verifica che sopravvive al sito di marketing dell’emittente. L’asserzione incorporata nomina l’emittente e punta al record ospitato, quindi un verificatore può partire dal solo file.

Flussi offline e a bassa tecnologia. Quando il payload è il JSON completo, un lettore può controllare l’affermazione su una macchina senza rete, poi verificare il record ospitato più tardi.

Una prova difficile da falsificare con leggerezza. Chiunque può fare lo screenshot di un badge. Uno screenshot non ha metadati, quindi non può essere verificato come file di badge. Già questo separa una credenziale vera da un’immagine copiata. Non impedisce però a qualcuno di incorporare un’asserzione falsa in un’immagine rubata, ed è per questo che esiste il passaggio di verifica ospitata.

I limiti del baking

Sii onesto con i tuoi destinatari su questi punti, perché influenzano il modo in cui descrivi le tue credenziali.

  • I metadati vengono rimossi. Molti social network, ottimizzatori di immagini e app di messaggistica ricodificano i caricamenti e scartano i chunk che non sono pixel. Un badge baked pubblicato su un feed social di solito non è più baked. È previsto, ed è il motivo per cui un link di verifica pubblico conta accanto al file.
  • Il baking da solo non è una prova. Il JSON incorporato può essere scritto da chiunque. La fiducia viene dall’asserzione ospitata sul dominio dell’emittente, o da una firma valida.
  • Le modifiche all’immagine spezzano il legame. Ridimensionare o risalvare in un editor può far perdere il chunk.
  • Solo PNG e SVG. Il JPEG non ha una convenzione di chunk equivalente nella specifica, quindi un badge in stile fotografico esportato in JPEG non può essere baked nel modo standard.

La conclusione pratica: considera il file baked un comodo veicolo, e la pagina di verifica l’autorità. Se stai valutando i formati per il tuo programma, Open Badges vs PDF certificates spiega perché una credenziale leggibile dalle macchine batte un documento statico.

Come funziona il baking su https://badges.ninja

Quando assegni un badge su https://badges.ninja, la piattaforma costruisce l’asserzione Open Badge per quel destinatario e la incorpora nell’immagine del badge durante l’emissione. Non devi configurare uno strumento né eseguire comandi. Il flusso:

  1. Progetti il badge nel designer visuale, oppure carichi la tua immagine.
  2. Emetti un riconoscimento, dalla dashboard, da un upload CSV per assegnazioni in blocco, o tramite API.
  3. La piattaforma crea l’asserzione, la incorpora nel PNG e conserva il risultato insieme al riconoscimento.
  4. Il destinatario riceve una pagina di verifica pubblica su https://badges.ninja/awards/<awardId>, un certificato PDF, un codice QR e un’opzione Add to LinkedIn.

Se il design del badge usa campi di unione come il nome del destinatario, ogni riconoscimento ottiene un’immagine personalizzata, ed è quell’immagine personalizzata a essere baked.

Il baking è trattato come un miglioramento dell’emissione, non come un blocco: se una particolare immagine non può essere baked (per esempio un’immagine segnaposto degenere), il riconoscimento viene comunque emesso usando l’immagine originale, e la pagina di verifica pubblica e il JSON-LD Open Badge non ne sono toccati. L’immagine che carichi deve anche superare una dimensione minima, così una minuscola tela vuota viene rifiutata prima di arrivare al forno.

Poiché la pagina pubblica è l’autorità, chiunque può controllare un riconoscimento senza registrarsi. Il JSON-LD Open Badge v2.0 leggibile dalle macchine di un riconoscimento è disponibile su https://api.badges.ninja/certify-badge/award/<awardId>.

Emettere un riconoscimento via API

La maggior parte dei lettori userà la dashboard, ma se automatizzi l’emissione basta una richiesta per creare il riconoscimento (e l’immagine baked arriva con esso). Sostituisci la chiave e l’id del badge con i tuoi:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": "bws_YOUR_KEY_HERE", "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId: "your-badge-id",
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();
const verifyUrl = `https://badges.ninja/awards/${awardId}`;

La chiamata restituisce HTTP 200 con { "awardId": "<guid>" }. Costruisci l’URL di verifica da quell’id. Per la configurazione delle chiavi e il riferimento completo delle richieste, vedi la Awards API docs e la authentication guide.

Badge detail screen in the https://badges.ninja dashboard

Consigli pratici per gli emittenti

Pubblica sempre un link di verifica accanto al file. Metti il link nell’email del riconoscimento, sul certificato e in ogni pagina dove il badge viene mostrato. Poiché le piattaforme social rimuovono i metadati, il link è ciò che mantiene la credenziale verificabile dopo la condivisione.

Usa un’immagine sorgente pulita e di buone dimensioni. Parti da un PNG con dimensioni reali. Un badge realizzato da un designer a risoluzione normale viene baked in modo affidabile; un segnaposto da 1 pixel no.

Non modificare il file consegnato. Di’ ai destinatari di condividere il download originale o il link di verifica, non uno screenshot ritagliato.

Decidi cosa vuoi dire su revoca e scadenza. Poiché il record ospitato è l’autorità, un file baked può sopravvivere allo stato della credenziale. Dillo chiaramente nella documentazione del tuo programma, così i datori di lavoro sapranno di controllare la pagina di verifica anziché fidarsi del solo file.

Prova un badge end to end. Emetti un riconoscimento a te stesso, scarica il PNG, passalo nello script qui sopra o in un validatore pubblico e apri il link di verifica. Cinque minuti di test ti dicono cosa vivranno i tuoi destinatari.

List of badges in the https://badges.ninja dashboard

Domande frequenti

Un badge baked è la stessa cosa di un certificato digitale? No. Un certificato è di solito un PDF da leggere e stampare. Un badge baked è un’immagine che porta anche dati di credenziale leggibili dalle macchine. https://badges.ninja produce entrambi dallo stesso riconoscimento.

Posso fare il baking di un badge senza una piattaforma? Sì. La specifica è aperta ed esistono librerie per diversi linguaggi. La parte più difficile è ospitare l’asserzione a un URL stabile, ciò che rende significativa la verifica. È la parte che una piattaforma gestisce per te.

Il baking espone l’email del destinatario? Non quando l’identità è sottoposta a hash. L’asserzione memorizza un hash con salt, quindi il file non rivela l’indirizzo.

LinkedIn leggerà i dati baked? Il flusso Add to Profile di LinkedIn funziona a partire da nome della credenziale, emittente, data e URL anziché dai metadati del file. Vedi adding an Add to LinkedIn button.

Un Open Badge baked è un PNG (o SVG) con la credenziale scritta in un chunk di testo chiamato openbadges. Rende un badge portabile e autodescrittivo, ma la vera fiducia viene dall’asserzione ospitata sul dominio dell’emittente. Fai il baking per la portabilità, pubblica un link di verifica per la fiducia e aspettati che i social network rimuovano i metadati.

Pronto a emettere la tua prima credenziale verificabile? Inizia gratis su badges.ninja — designer visuale, pagina di verifica pubblica, certificato PDF, output Open Badge v2.0. Nessuna carta di credito richiesta.

Nacho Coll

Informazioni sull'autore

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Torna al Blog

Articoli correlati