JSON-LD Badge Metadata: How Digital Badge Verification Works

When someone says a digital badge is "verifiable," there's actual machinery behind that claim. It's not a website showing a badge image with a name on it. It's structured data embedded in or linked to the badge, following a defined standard, with a verification chain that any independent tool can follow. That machinery is JSON-LD metadata.

This article explains how JSON-LD metadata works in digital badges, what it is, what fields it contains, how it ends up in (or linked to) a badge image, and how verification tools use it to confirm a badge is real. No programming experience required, though we do show real JSON examples, they're readable, we promise.

For the context on why this matters, start with What Are Open Badges? or the Digital Credentials Complete Guide.

What Is JSON-LD?

JSON stands for JavaScript Object Notation, a lightweight text format for representing structured data. It's used everywhere in web development because it's human-readable and machine-parseable. Here's what a simple JSON object looks like:

{
  "name": "Alex Smith",
  "award": "Data Science Foundations",
  "date": "2026-03-16"
}

The "LD" in JSON-LD stands for Linked Data. Linked Data is a method of connecting information on the web by referencing shared vocabularies, so that machines can understand the meaning of data, not just its structure. A plain JSON field called "date" is ambiguous, a date of what? JSON-LD resolves this by including a @context declaration that links the fields to defined meanings.

In Open Badges, the @context declaration points to the Open Badges vocabulary (a published JSON-LD context document). This means any machine reading a badge assertion knows that issuedOn means "the date this badge was issued," recipient means "the person who received this badge," and so on, not because of local conventions, but because of the shared vocabulary.

Badge Baking: embedding metadata in images

"Badge baking" is one of those terms that sounds mysterious but describes something elegantly simple: the process of embedding the badge's JSON-LD assertion metadata directly into the badge image file.

Digital image files, particularly PNG and SVG formats, support metadata fields that can store arbitrary text. In PNG files, this is done through "iTXt" chunks (international text chunks) in the PNG data structure. The badge assertion JSON is stored in one of these chunks, attached to the image data but not displayed visually.

What this means: when someone downloads their badge image, they're not just downloading a picture. They're downloading a picture that contains its own proof of authenticity. If they upload it to a verifier, the verifier reads the hidden metadata and checks the credential chain.

Not all badges are baked, though. In Open Badges 2.0, there are two delivery formats:

• Baked badges: The assertion JSON is embedded in the image. The badge file is self-contained.
• Hosted badges: The image contains only a reference URL. The actual assertion is hosted at that URL by the issuing platform.

Most modern badge platforms default to hosted badges, with baking available on request or automatically. Open Badges 3.0 shifts toward self-contained credentials (more like baked badges) because the cryptographic proof makes server-independent verification possible.

The three Badge objects and their fields

Open Badge metadata is organized into three interconnected JSON-LD objects. Here's each one with its key fields.

1. The Assertion

This is the individual credential record, the specific instance of a badge being awarded to a specific person. Every issued badge has exactly one assertion.

2. The BadgeClass

This is the template or definition of the badge, what it means, who grants it, and what's required to earn it. It's shared across all assertions of that badge type.

3. The issuer profile

Describes the organization or person issuing the badge. Verifiers fetch this to confirm who issued the badge and to retrieve the public key (in OB 3.0).

How recipient identity Is protected (Hashing)

A common question: is my email address visible in the badge metadata? The answer is no, and the mechanism used to protect it while still enabling verification is called hashing.

When an assertion is created, the recipient's email is not stored directly. Instead, a one-way mathematical function (a hash function, specifically SHA-256) is applied to the email, producing a fixed-length string that looks like gibberish. This hash is stored in the metadata. Also, a random "salt" value is added to the email before hashing, preventing rainbow-table attacks (pre-computed hash tables).

{
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "abc123randomsalt",
    "identity": "sha256$a9b8c7..."  // hash of salt+email
  }
}

To verify that a badge belongs to a specific person, the verifier takes the claimed email address, prepends the salt, hashes the result, and compares it to the stored hash. If they match, the badge belongs to that person. If they don't, it doesn't. Crucially, no one can reverse the hash to find the email address.

The verification flow, step by step

Hosted verification vs signed verification

There are two fundamentally different verification models in the Open Badges ecosystem, and the difference matters for long-term credential durability.

Hosted verification (OB 2.0)

The assertion is hosted at a URL maintained by the badge platform. Verification requires fetching live data from that URL. If the URL is down, the badge cannot be verified. The platform is the single point of truth.

Signed verification (OB 2.0 signed / OB 3.0)

The assertion is signed with the issuer's private key, and the signature is embedded in the badge. Verification checks the signature using the issuer's public key (fetched from a DID document or key URL). If the signature is valid, the badge is authentic, regardless of whether the issuing platform is online.

How OB 3.0 adds cryptographic proofs

In Open Badges 3.0, every credential must include a proof object in the JSON-LD. This proof contains the cryptographic signature and specifies the proof method used.

{
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-03-16T10:00:00Z",
    "verificationMethod": "did:web:issuebadge.com#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "z5rYqP2..."  // the actual signature
  }
}

The verificationMethod field points to the issuer's DID and a specific key. A verifier resolves this DID, retrieves the public key, and uses it to verify the signature. If the credential content has been altered at all, even a single character, the signature check fails.

What issuers need to know about their metadata

Most badge platforms handle metadata automatically. But there are things every issuer should verify about the metadata quality in their badges:

• Criteria URL is stable: The criteria URL in your BadgeClass should point to a stable, public page describing what was required to earn the badge. If this URL breaks, verifiers may get incomplete information.
• Issuer profile URL is publicly accessible: The issuer profile must be resolvable by verifiers. Ensure your platform hosts this at a stable URL and that it returns valid JSON-LD.
• Evidence is meaningful: Where possible, include evidence that actually demonstrates what the earner did, a project URL, an assessment record reference, or event attendance confirmation. This adds significant credibility.
• Badge image is standard format: For baking to work correctly, the badge image should be a standard PNG or SVG. Unusual image formats may not support metadata embedding.
• Test your badges on an independent verifier: Use a tool like Open Badge Passport or the 1EdTech Badge Validator to check that badges issued on your platform pass verification with correct metadata.