Open Badges Specification on GitHub openbadges/openbadges-specification

About Open Badges
FAQ for non-technical readers

Open Badges Examples

Open Badges consist of information about accomplishments stored in Badge Objects.

Examples of Core Open Badges objects

Information is divided between badge objects that describe an individual earner’s accomplishment (Assertion), the general features of the achievement (BadgeClass), and the entity or organization issuing the badge (Issuer)

Assertion Example (definition)

An example of a badge Assertion using the hosted verification method. This JSON object is “baked” into a badge image (optionally linked at the Assertion’s image property) and also hosted at the location specified by the @id and verify.url properties.

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://example.org/beths-robotics-badge.json",
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "deadsea",
    "identity": "sha256$c7ef86405ba71b85acd8e2e95166c4b111448089f2e1599f42fe1bba46e865c5"
  },
  "image": "https://example.org/beths-robot-badge.png",
  "evidence": "https://example.org/beths-robot-work.html",
  "issuedOn": "2016-12-31T23:59:59Z",
  "expires": "2017-06-30T23:59:59Z",
  "badge": "https://example.org/robotics-badge.json",
  "verification": {
    "type": "hosted"
  }
}

BadgeClass Example (definition)

The BadgeClass is hosted at the URI identified in associated Assertions’ badge property.

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "BadgeClass",
  "id": "https://example.org/robotics-badge.json",
  "name": "Awesome Robotics Badge",
  "description": "For doing awesome things with robots that people think is pretty great.",
  "image": "https://example.org/robotics-badge.png",
  "criteria": "https://example.org/robotics-badge.html",
  "tags": ["robots", "awesome"],
  "issuer": "https://example.org/organization.json",
  "alignment": [
    { "targetName": "CCSS.ELA-Literacy.RST.11-12.3",
      "targetUrl": "http://www.corestandards.org/ELA-Literacy/RST/11-12/3",
      "targetDescription": "Follow precisely a complex multistep procedure when 
      carrying out experiments, taking measurements, or performing technical 
      tasks; analyze the specific results based on explanations in the text.",
      "targetCode": "CCSS.ELA-Literacy.RST.11-12.3"
    },
    { "targetName": "Problem-Solving",
      "targetUrl": "https://learning.mozilla.org/en-US/web-literacy/skills#problem-solving",
      "targetDescription": "Using research, analysis, rapid prototyping, and feedback to formulate a problem and develop, test, and refine the solution/plan.",
      "targetFramework": "Mozilla 21st Century Skills"
    }
  ]
}

Notes:

Issuer/Profile Example (definition)

Metadata about the issuer is defined in JSON at a URL/IRI defined by the BadgeClass’s issuer property.

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Issuer",
  "id": "https://example.org/organization.json",
  "name": "An Example Badge Issuer",
  "image": "https://example.org/logo.png",
  "url": "https://example.org",
  "email": "contact@example.org",
  "publicKey": "https://example.org/publicKey.json",
  "revocationList": "https://example.org/revocationList.json"
}

Extension Examples (definition)

Extensions are formal sets of properties issuers and platforms add to the Open Badges Vocabulary. A number of community-developed extensions are published on the Extensions page with embedded examples of each.

Open Badges in Linked Data

Because Open Badges are Linked Data objects often hosted at HTTP IRIs, we can use the methods of identifying connections using Badge Objects can identify their connected resources either by their string IRI or by embedding a copy of the related document into the source document. For example, an Assertion may include its BadgeClass definition for portability instead of just linking to the URI of the BadgeClass object. Here, the BadgeClass and its issuer Profile record have been included in the Assertion. Each has its “id” property set to the URI where it is published, the unique identifier for that object. Displayer platforms can use that value to index these records.

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "https://example.org/beths-robotics-badge.json",
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "deadsea",
    "identity": "sha256$c7ef86405ba71b85acd8e2e95166c4b111448089f2e1599f42fe1bba46e865c5"
  },
  "issuedOn": "2016-12-31T23:59:59Z",
  "badge": {
    "id": "https://example.org/robotics-badge.json",
    "type": "BadgeClass",
    "name": "Awesome Robotics Badge",
    "description": "For doing awesome things with robots that people think is pretty great.",
    "image": "https://example.org/robotics-badge.png",
    "criteria": "https://example.org/robotics-badge.html",
    "issuer": {
      "type": "Profile",
      "id": "https://example.org/organization.json",
      "name": "An Example Badge Issuer",
      "image": "https://example.org/logo.png",
      "url": "https://example.org",
      "email": "steved@example.org",
    }
  },
  "verification": {
    "type": "hosted"
  }
}

Notes:

Additional Vocabulary Classes Examples

While the Assertion, BadgeClass, and Profile are the minimal set of JSON-LD resources necessary for a valid badge, there are several secondary data classes that extend the usefulness, security, and portability of Open Badges. The examples below are often abbreviated to highlight a specific feature, so not all examples contain all the required properties to constitute a valid Badge Object of their type.

Signed Badges Example (definition)

JSON Web Signatures, a branch of the JSON Object Signing and Encryption (JOSE) group of standards is a signature method accepted for Open Badges objects. A JSON Web Signature (JWS) for a signed Assertion is made up of three components, packaged as a string with .s used as separators. (Space has been added here around the . separators for clarity.) This example is not a valid JWS, as the referenced key on example.org does not exist.

eyJhbGciOiJSUzI1NiJ9
.
ew0KICAiQGNvbnRleHQiOiAiaHR0cHM6Ly93M2lkLm9yZy9vcGVuYmFkZ2VzL3YyIiwNCiAgInR5cGUiOiAiQXNzZXJ0aW9uIiwNCiAgImlkIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvYmV0aHMtcm9ib3RpY3MtYmFkZ2UuanNvbiIsDQogICJyZWNpcGllbnQiOiB7DQogICAgInR5cGUiOiAiZW1haWwiLA0KICAgICJoYXNoZWQiOiB0cnVlLA0KICAgICJzYWx0IjogImRlYWRzZWEiLA0KICAgICJpZGVudGl0eSI6ICJzaGEyNTYkYzdlZjg2NDA1YmE3MWI4NWFjZDhlMmU5NTE2NmM0YjExMTQ0ODA4OWYyZTE1OTlmNDJmZTFiYmE0NmU4NjVjNSINCiAgfSwNCiAgImltYWdlIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvYmV0aHMtcm9ib3QtYmFkZ2UucG5nIiwNCiAgImV2aWRlbmNlIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvYmV0aHMtcm9ib3Qtd29yay5odG1sIiwNCiAgImlzc3VlZE9uIjogIjIwMTYtMTItMzFUMjM6NTk6NTlaIiwNCiAgImJhZGdlIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvcm9ib3RpY3MtYmFkZ2UuanNvbiIsDQogICJ2ZXJpZnkiOiB7DQogICAgInR5cGUiOiAiU2lnbmVkQmFkZ2UiLA0KICAgICJjcmVhdG9yIjogImh0dHBzOi8vZXhhbXBsZS5vcmcvcHVibGljS2V5Ig0KICB9DQp9
.
Liv4CLviFH20_6RciUWf-jrUvMAecxT4KZ_gLHAeT_chrsCvBEE1uwgtwiarIs9acFfMi0FJzrGye6mhdHf3Kjv_6P7BsG3RPkYgK6-5i9uZv4QAIlvfNclWAoWUt4j0_Kip2ftzzWwc5old01nJRtudZHxo5eGosSPlztGRE9G_g_cTj32tz3fG92E2azPmbt7026G91rq80Mi-9c4bZm2EgrcwNBjO0p1mbKYXLIAAkOMuJZ_8S4Go8S0Sg3xC6ZCn03zWuXCP6bdY_jJx2BpmvqC3H55xWIU8p5c9RxI8YifPMmJq8ZQhjld0pl-L8kHolJx7KGfTjQSegANUPg

When base64 decoded this corresponds to the three JSON objects below for a signed 2.0 Open Badge:

Header:

{ "alg": "RS256" }

Claims:

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Assertion",
  "id": "urn:uuid:a953081a-4bbd-4927-9653-7219bca00e3b",
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "deadsea",
    "identity": "sha256$c7ef86405ba71b85acd8e2e95166c4b111448089f2e1599f42fe1bba46e865c5"
  },
  "evidence": "https://example.org/beths-robot-work.html",
  "issuedOn": "2016-12-31T23:59:59Z",
  "badge": "https://example.org/robotics-badge.json",
  "verification": {
    "type": "SignedBadge",
    "creator": "https://example.org/publicKey.json"
  }
}

Signature:

Liv4CLviFH20_6RciUWf-jrUvMAecxT4KZ_gLHAeT_chrsCvBEE1uwgtwiarIs9acFfMi0FJzrGye6mhdHf3Kjv_6P7BsG3RPkYgK6-5i9uZv4QAIlvfNclWAoWUt4j0_Kip2ftzzWwc5old01nJRtudZHxo5eGosSPlztGRE9G_g_cTj32tz3fG92E2azPmbt7026G91rq80Mi-9c4bZm2EgrcwNBjO0p1mbKYXLIAAkOMuJZ_8S4Go8S0Sg3xC6ZCn03zWuXCP6bdY_jJx2BpmvqC3H55xWIU8p5c9RxI8YifPMmJq8ZQhjld0pl-L8kHolJx7KGfTjQSegANUPg

Using Cryptographic Keys

In the above example, a keypair with publicKey identifier https://example.org/publicKey.json was used to sign a badge Assertion. The following resources should exist for this to be a functional example:

Type id Description
Assertion urn:uuid:a953081a-4bbd-4927-9653-7219bca00e3b There is no HTTP(s) id for this Assertion, because it was delivered as a JWS. It links to the BadgeClass document with the badge property. See immediately above.
BadgeClass https://example.org/robotics-badge.json A BadgeClass document that links to the Issuer. See above.
Profile https://example.org/organization.json A issuer Profile document that links to the CryptographicKey document with its publicKey property. See above
PublicKey https://example.org/publicKey.json A CryptographicKey document that links to the issuer Profile with its owner property. See below](#CryptographicKey).

CryptographicKey Example (definition)

A public key document should describe an Open Badges issuer’s public key. For maximum compatibility, it should have its own HTTP(S) identifier, and should identify its issuer using the owner property. The publicKeyPem shown below has been abbreviated with ... for readability.

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "CryptographicKey",
  "id": "https://example.org/publicKey.json",
  "owner": "https://example.org/organization.json",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBG0BA...OClDQAB\n-----END PUBLIC KEY-----\n"
}

RevocationList Example (definition)

Issuers may have a RevocationList if they use SignedBadge verification. Checking this list is intended as part of the verification process for signed badges, just as checking for the hosted assertion is part of verifying a hosted badge. It is published as a JSON-LD document with type RevocationList. RevocationLists are linked from an issuer Profile via the revocationList property. The RevocationList identifies its issuer with the issuer property.

RevocationLists may identify revoked Assertions through their revokedAssertions property. Individual assertions are identified either by their id or (legacy) uid properties. id-identified Assertions may appear in a RevocationList as that id string or as an object with an id property and other metadata, usually just a revocationReason. The below example shows ids in the urn:uuid namespace, which is a recommended namespace for signed Assertions that do not have a hosted (HTTP) id.

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/revocationList.json",
  "type": "RevocationList",
  "issuer": "https://example.org/issuer",
  "revokedAssertions": [
    "urn:uuid:3c574c87-b96f-4f06-8eb5-68a29335b60e",
    {
      "id": "urn:uuid:e79a6c18-787e-4868-8e65-e6a4530fb418",
      "revocationReason": "Honor code violation"
    },
    {
      "uid": "abc123",
      "revocationReason": "Issued in error."
    }
  ]
}

Revoked Hosted Assertion Example (see more about Hosted Verification)

Revoked hosted Assertions should be returned with the HTTP status 410 Gone. The response body may contain an Assertion document with "revoked": true that contains additional metadata. It does not need to meet the full requirements of the Assertion class. Only id and revoked properties must be present

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "revoked": true,
  "revocationReason": "Turns out the student's robot was just three stacked children in a trenchcoat with dryer vent hose arms."
}

Criteria Example (definition)

A BadgeClass’s criteria field may be populated with a HTTP(s) URI string or an instance of the Criteria class. Here, a URI is used:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "criteria": "https://example.org/robotics-badge.html"
}

Embedding criteria into the badge allows display platforms to render criteria information to viewers without directing them to an external website. It may be used in parallel to a criteria URI as follows:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "criteria": {
    "id": "https://example.org/robotics-badge.html",
    "narrative": "To earn the **Awesome Robotics Badge**, students must construct a
    basic robot.\n\nThe robot must be able to:\n\n  * Move forward and backwards.\n
    * Pick up a bucket by its handle."
  }
}

The Criteria class may also appear without using an external URI to increase portability, as fewer information dependencies then exist outside of the JSON-LD metadata. Additionally, the narrative can be used to make complex links with the BadgeClass’s alignment targets.

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "criteria": {
    "id": "https://example.org/robotics-badge.html",
    "narrative": "To earn the **Awesome Robotics Badge**, students must construct a
    basic robot.\n\nThe robot must be able to:\n\n  * Move forward and backwards 
    [1](https://example.org/robot-skills/1).\n  * Pick up a bucket by its handle
    [2](https://example.org/robot-skills/2)."
  },
  "alignment": [
    {
      "targetUrl": "https://example.org/robot-skills/1",
      "targetName": "Basic Locomotion"
    },
    {
      "targetUrl": "https://example.org/robot-skills/2",
      "targetName": "Object Manipulation"
    }
  ]
}

Evidence Example (definition)

Metadata related to evidence may be included in Assertions in several ways.

The issuer may provide a text/Markdown narrative describing the evidence:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "narrative": "This student invented her own type of robot. This included: \n\n  * Working robot arms\n  * Working robot legs"
}

Evidence may be referenced by URI id:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "evidence": "https://example.org/beths-robot-work.html"
}

Evidence may be more fully described by using the Evidence class:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "evidence": {
    "id": "https://example.org/beths-robot-work.html",
    "name": "My Robot",
    "description": "A webpage with a photo and a description of the robot the student built for this project.",
    "narrative": "The student worked very hard to assemble and present a robot. She documented the process with photography and text.",
    "genre": "ePortfolio"
}

It is possible to include multiple values for evidence in an Assertion. Evidence may be more fully described by using the Evidence class:

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "narrative": "This student invented her own type of robot. This included: \n\n  * Working robot arms\n  * Working robot legs",
  "evidence": [
    {
      "id": "https://example.org/beths-robot-photos.html",
      "name": "Robot Photoshoot",
      "description": "A gallery of photos of the student's robot",
      "genre": "Photography"
    },
    {
      "id": "https://example.org/beths-robot-work.html",
      "name": "Robotics Reflection #1",
      "description": "Reflective writing about the first week of a robotics learning journey."
    }
  ]

Image Example (definition)

In order to provide extra useful information for rendering images, sometimes additional metadata about images is included in Badge Objects using the Image class.

Images are often referenced by their HTTP URI where they may be accessed. Displayers usually render this as the image source in HTML.

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "image": "https://example.org/beths-robot-badge.png"
}

However, additional properties are available, and can be referenced wherever images appear in Badge Objects. For example, a caption can aid in rendering alt text in browsers. If author is used, it may be the id of an Open Badges Profile, but it may be another id that represents the author. Displayers should not assume this is a URI that will resolve to a compatible instance of a Profile.

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge.json",
  "image": {
    "id": "https://example.org/beths-robot-badge.png",
    "caption": "A pretty badge, with many happy trees.",
    "author": "https://en.wikipedia.org/wiki/Bob_Ross"
  }
}

Social Media URLs in Profiles

When using the url property of a profile to denote a social media account, use the canonical url of the account. For example, for a Twitter account, use https://twitter.com/OpenBadges. For a Facebook page or account, the URL is in the format https://www.facebook.com/OpenBadges.

BadgeClass Versioning

The version property allows issuers to set a version number or string for a BadgeClass. This is particularly useful when replacing a previous version with an update.

{
  "@context": "https://w3id.org/openbadges/v2",
  "id": "https://example.org/beths-robotics-badge-v2.json",
  "name": "Awesomer Robotics Badge",
  "version": 2,
  "related": {
    "id": "https://example.org/beths-robotics-badge.json",
    "version": 1
  }
}

Internationalization Examples

The string internationalization features of JSON-LD make it possible for issuers to declare which language a Badge Object is expressed in:

{
  "@context": "https://w3id.org/openbadges/v2",
  "@language": "en-us",
  "id": "https://example.org/beths-robotics-badge.json",
  "name": "Awesome Robotics Badge"
}

It is also possible to list multiple versions of Badge Objects to make available multiple equivalent versions of the same entity.

{
  "@context": "https://w3id.org/openbadges/v2",
  "@language": "en-us",
  "id": "https://example.org/beths-robotics-badge.json",
  "name": "Awesome Robotics Badge",
  "related": [{
      "id": "https://example.org/beths-robotics-badge-es.json?l=es",
      "@language": "es"
    }]
}

Notes:

Endorsement Examples

An endorser can use an Endorsement to indicate trust in an email address. Suppose the issuer Profile record above exists, but inspectors are unsure whether it is a trustworthy record that truly represents the organization it describes. Endorsements can show that an external party has verified one or more properties of the Issuer. Automated services could be developed to verify properties like email or telephone, and human verification services could provide more in-depth verification.

Here, an endorser claims to have verified the email address published in the Profile.

{
 "@context": "https://w3id.org/openbadges/v2",
 "type": "Endorsement",
 "id": "https://example.org/endorsement-123.json",
 "issuer": "https://example.org/issuer-5.json",
 "claim": {
   "id": "https://example.org/organization.json",
   "email": "contact@example.org",
 },
 "verification": {
   "type": "hosted"
 }
}

Another prominent use of Endorsements is to provide a comment expressing approval of a BadgeClass, that it is a good representation of the achievement it describes. The endorser could publish the following about the above BadgeClass.

{
 "@context": "https://w3id.org/openbadges/v2",
 "type": "Endorsement",
 "id": "https://example.org/endorsement-124.json",
 "issuer": "https://example.org/issuer-5.json",
 "claim": {
   "id": "https://example.org/robotics-badge.json",
   "endorsementComment": "This badge and its associated learning material are great examples of beginning robotics education."
 },
 "verification": {
   "type": "hosted"
 }
}

The same method could be used to support a single recipient’s achievement through endorsing an Assertion. Here the endorser also offers an addition to the evidence to be considered associated with the badge.

{
 "@context": "https://w3id.org/openbadges/v2",
 "type": "Endorsement",
 "id": "https://example.org/endorsement-125.json",
 "issuer": "https://example.org/issuer-5.json",
 "claim": {
   "id": "https://example.org/beths-robotics-badge.json",
   "endorsementComment": "This student built a great robot.",
   "evidence": "https://example.org/photos/my-photos-of-the-robot-competition.html"
 },
 "verification": {
   "type": "hosted"
 }
}