Open Badge Baking explicado: como o JSON vive dentro do PNG

Um Open Badge «baked» é um PNG com o JSON da asserção embutido como metadados da imagem. O arquivo do emblema É a credencial. Como o baking funciona e como verificar um emblema baked.

Nacho Coll Por Atualizado 12 min de leitura
Um Open Badge «baked» é um PNG com o JSON da asserção embutido como metadados da imagem. O arquivo do emblema É a credencial. Como o baking funciona e como verificar um emblema baked.

Baixe um Open Badge de quase qualquer emissor e você recebe um PNG de aparência normal. Jogue num chat, anexe a um e-mail, imprima. Parece uma imagem qualquer. Mas o arquivo carrega uma segunda camada invisível: a própria credencial, gravada na imagem como metadados. É isso que a comunidade Open Badges chama de emblema baked (assado), e é por isso que um emblema pode viajar como um único arquivo e ainda provar quem o emitiu, para quem e por quê.

Este guia explica o que é baking, onde os dados ficam dentro do arquivo, como um verificador os lê de volta e o que você precisa decidir como emissor de credenciais. Você não precisa escrever código para usar emblemas baked. Se você emite pelo https://badges.ninja, o baking acontece por você. Mas entender a mecânica ajuda a responder às perguntas que destinatários e empregadores realmente fazem: «Esta imagem é verdadeira?» e «Qualquer pessoa pode simplesmente copiar?»

O que «baking» significa

Um Open Badge tem duas partes fáceis de confundir:

  • A imagem. O PNG ou SVG que as pessoas veem em um perfil, em um slide ou em um certificado.
  • A asserção. Um pequeno documento JSON que declara os fatos: quem é o destinatário (como identificador com hash), qual classe de emblema foi conquistada, quem emitiu, quando e onde verificar.

Baking é o ato de gravar a asserção dentro da imagem para que as duas não possam ser separadas. O resultado é um único arquivo. Entregue o PNG a alguém e você entregou a imagem e a declaração por trás dela.

A ideia vem da especificação Open Badges, desenvolvida originalmente pela Mozilla e hoje mantida pela 1EdTech. O objetivo do design é a portabilidade. No início, os emblemas viviam dentro de uma única plataforma, e movê-los para outro lugar significava reenviar e torcer para que os metadados sobrevivessem. Um arquivo baked leva seus próprios metadados aonde for.

Onde o JSON fica dentro de um PNG

Um arquivo PNG é uma assinatura curta seguida de uma sequência de chunks (blocos). Cada chunk tem um comprimento, um tipo de quatro letras, alguns dados e uma soma de verificação. Os visualizadores desenham os pixels a partir dos chunks IDAT e ignoram os tipos de chunk que não entendem. Essa tolerância é o que torna o baking possível: você pode adicionar um chunk cheio de texto e todos os visualizadores de imagem do mundo continuarão exibindo a imagem normalmente.

No Open Badges 2.0, a asserção vai em um chunk de texto com a palavra-chave openbadges. Os tipos de chunk de texto que podem contê-la são:

ChunkCodificaçãoObservações
tEXtLatin-1Simples, mas limitado a caracteres Latin-1.
iTXtUTF-8Preferido, porque nomes e descrições muitas vezes não são ASCII.

Qualquer que seja o chunk usado, a estrutura é a mesma: a palavra-chave openbadges, um separador e depois a carga útil. A carga útil é uma de duas coisas, dependendo de como o emissor escolheu fazer o baking:

  1. O próprio JSON da asserção. O arquivo é autodescritivo. Um verificador pode ler a declaração sem nenhuma chamada de rede.
  2. Uma URL que aponta para a asserção hospedada. O arquivo fica menor e o emissor pode manter o registro ativo como autoridade, por exemplo para mostrar que um emblema foi revogado depois ou expirou.

Existe uma terceira variante para emblemas assinados, em que a carga útil é um token assinado em vez de JSON puro. Se assinaturas importam no seu caso, leia como verificar a assinatura de um Open Badge.

E o SVG?

Emblemas SVG também podem ser baked, já que SVG é XML. A asserção é colocada dentro do arquivo em um elemento do namespace XML openbadges, e o atributo verify carrega a URL da asserção hospedada. O princípio é o mesmo do PNG: os metadados viajam dentro do arquivo de imagem. Na prática, a maioria das plataformas faz baking em PNG, porque o PNG é aceito em quase todo lugar onde as pessoas querem enviar um emblema.

Como é a asserção embutida

No formato 2.0, uma asserção hospedada é JSON-LD que liga o destinatário, a classe do emblema e o método de verificação. Um exemplo reduzido:

{
  "@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" }
}

Repare no destinatário. O e-mail não é guardado em texto claro; é um hash SHA-256 com salt. Isso importa para um arquivo feito para circular. Qualquer pessoa com o PNG pode ler a asserção, então ela não pode vazar o endereço do destinatário. Um verificador que já conhece o e-mail pode aplicar o hash com o mesmo salt e conferir se bate. Para um passeio campo a campo por esse documento, veja o passo a passo do JSON-LD de um Open Badge.

Como um verificador lê um emblema baked

A verificação de um emblema baked é um processo curto e mecânico:

  1. Abra o PNG e percorra seus chunks.
  2. Encontre o chunk de texto com a palavra-chave openbadges.
  3. Leia a carga útil. Se for JSON, faça o parse. Se for uma URL, busque-a.
  4. Confira se a asserção se refere à classe de emblema e ao emissor que você espera, e se a identidade do destinatário corresponde à pessoa que o apresenta.
  5. Se o tipo de verificação for hosted, confirme que a asserção hospedada ainda existe na URL id e não foi revogada nem expirou.

O passo 5 é o que as pessoas pulam, e é o que torna uma credencial confiável. Uma cópia embutida é um instantâneo. O registro hospedado é a fonte da verdade.

Lendo você mesmo em Node

Você pode inspecionar qualquer PNG com um script curto. Este percorre os chunks e imprime a carga útil openbadges, tratando tanto tEXt quanto 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);

Execute com node extract-badge.mjs my-badge.png. Se o arquivo for baked, você verá JSON ou uma URL. Se não, receberá uma simples mensagem «not baked». É uma ferramenta didática, não um validador completo: ela não confere as somas de verificação dos chunks, não interpreta cargas úteis assinadas nem busca o registro hospedado.

Se preferir não escrever código, um validador de emblemas online ou um visualizador de metadados de PNG mostrará o mesmo chunk. O formato é o padrão, então qualquer ferramenta compatível lê qualquer emblema compatível.

Por que o baking importa

Portabilidade. Uma credencial que é só um PNG pode ser enviada por e-mail, carregada em uma plataforma de aprendizagem ou guardada em um arquivo pessoal. Não é preciso ter conta para carregá-la.

Um caminho de verificação que sobrevive ao site de marketing do emissor. A asserção embutida nomeia o emissor e aponta para o registro hospedado, então um verificador pode começar só com o arquivo.

Fluxos offline e de baixa tecnologia. Quando a carga útil é o JSON completo, o leitor pode conferir a declaração em uma máquina sem rede e verificar o registro hospedado depois.

Evidência difícil de falsificar casualmente. Qualquer um pode tirar um print de um emblema. Um print não tem metadados, então não pode ser verificado como arquivo de emblema. Só isso já separa uma credencial real de uma imagem copiada. Isso não impede alguém de gravar uma asserção falsificada em uma imagem roubada, e é por isso que existe a etapa de verificação hospedada.

Os limites do baking

Seja honesto com seus destinatários sobre isto, porque afeta como você descreve suas credenciais.

  • Metadados são removidos. Muitas redes sociais, otimizadores de imagem e apps de mensagem recodificam os envios e descartam chunks que não são pixels. Um emblema baked publicado em um feed social normalmente deixa de ser baked. É esperado, e por isso um link público de verificação importa junto com o arquivo.
  • O baking não é prova por si só. Qualquer pessoa pode escrever JSON embutido. A confiança vem da asserção hospedada no domínio do emissor, ou de uma assinatura válida.
  • Editar a imagem quebra o vínculo. Redimensionar ou salvar de novo em um editor pode perder o chunk.
  • Somente PNG e SVG. O JPEG não tem uma convenção de chunk equivalente na especificação, então um emblema estilo foto exportado como JPEG não pode ser baked do jeito padrão.

A conclusão prática: trate o arquivo baked como um transportador conveniente e a página de verificação como a autoridade. Se você está comparando formatos para o seu programa, Open Badges vs certificados em PDF explica por que uma credencial legível por máquina supera um documento estático.

Como o baking funciona no https://badges.ninja

Quando você concede um emblema no https://badges.ninja, a plataforma monta a asserção Open Badge para aquele destinatário e a grava na imagem do emblema como parte da emissão. Você não configura nenhuma ferramenta nem executa nenhum comando. O fluxo:

  1. Você desenha o emblema no designer visual, ou envia sua própria imagem.
  2. Você emite um prêmio, pelo painel, por um upload de CSV para prêmios em lote ou pela API.
  3. A plataforma cria a asserção, grava no PNG e armazena o resultado com o prêmio.
  4. O destinatário recebe uma página pública de verificação em https://badges.ninja/awards/<awardId>, um certificado em PDF, um QR code e uma opção Add to LinkedIn.

Se o design do emblema usa campos de mesclagem, como o nome do destinatário, cada prêmio recebe uma imagem personalizada, e é essa imagem personalizada que é baked.

O baking é tratado como um aprimoramento da emissão, não como uma barreira: se uma imagem específica não puder ser baked (por exemplo, uma imagem placeholder degenerada), o prêmio ainda é emitido usando a imagem original, e a página pública de verificação e o JSON-LD do Open Badge não são afetados. A imagem que você enviar também precisa atingir um tamanho mínimo, então um canvas minúsculo e em branco é rejeitado antes de chegar à padaria.

Como a página pública é a autoridade, qualquer pessoa pode conferir um prêmio sem se cadastrar. O JSON-LD legível por máquina do Open Badge v2.0 de um prêmio está disponível em https://api.badges.ninja/certify-badge/award/<awardId>.

Emitindo um prêmio pela API

A maioria dos leitores vai usar o painel, mas se você automatiza a emissão, uma única requisição cria o prêmio (e a imagem baked vem junto). Substitua a chave e o id do emblema pelos seus:

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}`;

A chamada retorna HTTP 200 com { "awardId": "<guid>" }. Monte a URL de verificação a partir desse id. Para a configuração de chaves e a referência completa da requisição, veja a documentação da API de Awards e o guia de autenticação.

Tela de detalhes de um emblema no painel do https://badges.ninja

Conselhos práticos para emissores

Sempre publique um link de verificação junto ao arquivo. Coloque o link no e-mail do prêmio, no certificado e em qualquer página onde o emblema seja exibido. Como as plataformas sociais removem os metadados, o link é o que mantém a credencial verificável depois de compartilhada.

Use uma imagem de origem limpa e de bom tamanho. Comece de um PNG com dimensões reais. Um emblema feito por um designer em resolução normal sofre baking de forma confiável; um placeholder de 1 pixel, não.

Não edite o arquivo entregue. Diga aos destinatários para compartilharem o download original ou o link de verificação, não um print cortado.

Decida o que você quer dizer sobre revogação e expiração. Como o registro hospedado é a autoridade, um arquivo baked pode sobreviver ao status da credencial. Diga isso com clareza na documentação do seu programa para que os empregadores saibam que devem consultar a página de verificação em vez de confiar só no arquivo.

Teste um emblema de ponta a ponta. Emita um prêmio para você mesmo, baixe o PNG, passe-o pelo script acima ou por um validador público e abra o link de verificação. Cinco minutos de teste mostram o que seus destinatários vão experimentar.

Lista de emblemas no painel do https://badges.ninja

Perguntas frequentes

Um emblema baked é o mesmo que um certificado digital? Não. Um certificado costuma ser um PDF para ler e imprimir. Um emblema baked é uma imagem que também carrega dados de credencial legíveis por máquina. O https://badges.ninja produz os dois a partir do mesmo prêmio.

Posso fazer baking de um emblema sem uma plataforma? Sim. A especificação é aberta e existem bibliotecas para várias linguagens. A parte mais difícil é hospedar a asserção em uma URL estável, que é o que dá sentido à verificação. Essa é a parte que uma plataforma resolve por você.

O baking expõe o e-mail do destinatário? Não quando a identidade tem hash. A asserção guarda um hash com salt, então o arquivo não revela o endereço.

O LinkedIn lê os dados baked? O fluxo Add to Profile do LinkedIn funciona a partir do nome da credencial, emissor, data e URL, e não dos metadados do arquivo. Veja como adicionar um botão Add to LinkedIn.

Resumo

Um Open Badge baked é um PNG (ou SVG) com a credencial gravada em um chunk de texto chamado openbadges. Ele torna um emblema portátil e autodescritivo, mas a confiança de verdade vem da asserção hospedada no domínio do emissor. Faça baking pela portabilidade, publique um link de verificação pela confiança e espere que as redes sociais removam os metadados.

Pronto para emitir sua primeira credencial verificável? Comece grátis no badges.ninja — designer visual, página pública de verificação, certificado em PDF, saída Open Badge v2.0. Sem cartão de crédito.

Nacho Coll

Sobre o autor

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.

Voltar ao Blog

Artigos Relacionados