Concentric Sky

Menu

Nate Otto // February 7, 2017

Developer’s Guide to Issuing Open Badges 2.0

Cute kid with Trophy.

Open Badges are verifiable records of achievement that are published as JSON-LD records using the core Assertion, BadgeClass, and Profile classes of the Open Badges Vocabulary. The Open Badges Specification provides instructions on how these records may be published, transmitted, and verified by applications serving different roles in the Open Badges Ecosystem, such as Issuer, Backpack, Verifier, Displayer, or Consumer.

This post will outline some of the new features and what developers need to know about implementation. See the existing developers’ guide which is up-to-date for Open Badges 1.1. This post won’t go into as much detail and will focus on what is new or different about 2.0.

Status of 2.0

The Badge Alliance, formed in 2014, gathered and refined the use cases that were implemented in 2.0 for over two years, leading to both the release of the 1.1 recommendation in May 2015 and 2.0 in December 2016. At the same time, community members organized to create a long term sustainable future for Open Badges by bringing it before the established web standards community.

As a culmination of this effort, in January 2017, Open Badges was formally accepted into the care of IMS Global, an international member-funded standards organization that operates in the educational technology space, releasing standards such as Learning Tools Interoperability (LTI) and [Common Cartridge](https://goo.gl/ePUeGR. IMS took over from the Badge Alliance, which was the initial home of Open Badges as the Specification made its first steps out from under the wings of the Mozilla Foundation. As of December 31, 2016, the Badge Alliance released its final 2.0 Recommendation and handed the ball over to IMS for finalization. That recommendation is published on openbadgespec.org and has become the “Base Document” that will be adapted by March to become the working draft that IMS will coordinate with its supplier community to implement.

The working draft will feature a few spelling corrections, but likely no material changes from the BA recommendation. After two interoperable issuer implementations and a working validator are finished, IMS will move to finalize 2.0. There is an opportunity for modification to the specification during implementation to address any show-stopper issues that arise, so the existing recommendation should not be assumed to be identical to the final draft to be sent to finalization, but all indicators point to very few changes pending successful implementation.

Let’s talk about how to implement. Open Badges 2.0 is intended to be a very simple upgrade for nearly all issuers, while providing a rich set of new options that enhance badge expressiveness, security, and portability. The new options are almost all optional enhancements from what was available in 1.1. This means that backpack services and verifiers have significant work to do as they upgrade to 2.0, but the benefits they can realize from increased machine-readable metadata and more explicit validity rules make 2.0 an enormous improvement for services that display and make use of Open Badges. I’ll talk about the changes for verification in a future post.

How to Issue Badges

Issuing Open Badges requires constructing and publishing a set of interconnected resources that follow the structure and guidelines set out in the Specification. The properties that make up a badge’s metadata are split across these resources depending on where they apply. Together they form an Open Badge. For each badge awarded, there’s one each of an issuer Profile, a Badgeclass, and an Assertion, linked together. These three components are instances of “Open Badges Vocabulary Data Classes”. Profile, BadgeClass, and Assertion are like recipes for describing certain types of information. The Specification describes the properties available in each one, which are required, and what sort of values are allowed for each one. In some cases, it requires the property value in one class to be an instance of another, which means embedding a JSON “object” (denoted as a list of that class’s properties within another set of { } curly braces inside the first instance). Let’s start with Profile, BadgeClass and Assertion.

  • The issuer Profile describes the individual or organization awarding badges. In 2.0, the Profile class is used to describe both issuers and recipients of badges. For issuers, the Profile must have a canonical published at an HTTP URI which appears as the profile’s id property. New in 2.0 is the inclusion of verification instructions for Assertions awarded by this profile, which allows issuers to be explicit about how they award badges. This also allows verifiers to fall back to enforcing a newly clarified default setting for “hosted” Assertions.
  • The BadgeClass describes the achievement in terms of metadata such as name, description, image, and criteria. It links back to the issuer by its id or by embedding the issuer Profile record. The BadgeClass must also have an id that takes the form of an Internationalized Resource Identifier (IRI), but in 2.0, issuers may use an ephemeral id and are no longer required to have an HTTP identifier and associated hosted record but can use other identifiers. The urn:uuid scheme is recommended for cases where there is no HTTP-hosted record. Criteria may now be either a URL, as in previous versions, or an embedded instance of the new Criteria class, in order to relieve issuers of the requirement to host yet another record and to allow badges to be more robustly machine readable.
  • The Assertion is the record of an individual’s achievement of the badge. It links to the BadgeClass by id or an embedded BadgeClass record. Assertions have always identified their recipients by a string-based property, but 2.0 is more explicit about how Assertions identify those recipients, opening up the possibility for badges to be awarded to other issuers, to organizations identified by url, to individuals identified by a social media profile url or telephone number as well as the most common method, email. Assertions contain brief verification instructions to indicate which verification procedure should be followed from those instructions, such as specifying that the id of the Assertion is an HTTP identifier where a canonical copy may be retrieved, or that the Assertion will be delivered as a record cryptographically signed with a specific one of the issuer’s defined keypairs. New metadata is also available for Assertions in the form of the option to include Evidence records and narratives that describe the process of meeting criteria, potentially connecting multiple evidence records and alignments.

There are a number of other complementary data classes that may be mixed in. I mentioned Criteria and Evidence, but several other new and updated classes are available as well. Those include an updated AlignmentObject and RevocationList as well as new classes CryptographicKey and Image.

A simple example

Here is a hypothetical example Open Badge that shows some of the new features in action.

Issuer: An issuer establishes a Profile, by hosting the following JSON on their website available at https://example.org/organization.json:

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Profile",
  "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",
  "verification": {
    "allowedOrigins": ["example.org", "two.example.org"],
    "verificationProperty": "id"
  }
}

This is almost identical to what the issuer would have published under 1.1. They have updated the context URI and are using the new Profile type declaration. The previously used Issuer may also be used as a type. It is now considered a subclass of the more general Profile. In addition, the issuer has chosen to specify a verification policy, in which they make one change from the default behavior to also authorize assertions on a second origin under their control, two.example.org.

BadgeClass: The next step is to define a BadgeClass that links to this Profile. The Issuer chooses to make this record available at https://example.org/robotics-badge.json:

{
  "@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": {
    "id": "https://example.org/robot-badge.png",
    "caption": "A pretty badge, with many happy trees.",
    "author": "http://example.org/Bob_Ross_profile.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."
  },
  "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"
    }
  ]
}

There are several 2.0 implementation options showcased here:

  • The issuer is identified by URL. Another option would have been to embed the issuer profile JSON above almost exactly as it is independently published. This allows for better portability in some cases, where the trustworthiness of the BadgeClass is well-established.
  • The author has chosen to provide additional metadata about the badge image by embedding an instance of the Image class instead of just providing the image URI like "image": "https://example.org/robot-badge.png". This allows displayers to use the included caption to render alt text to improve accessibility.
  • The issuer has chosen to embed criteria information and include a link to an external URL. At least one option is required, though if issuers only wanted to link to a URL, they could go directly by using the 1.1 format "criteria": "https://example.org/robotics-badge.html". Embedding a criteria narrative allows display platforms to show information about how to earn the badge directly to viewers in their application instead of only being able to render a link.
  • The updated term names for alignment are used. Previously, alignment would use name, description, and url. The new property named targetCode identifies a code string within the target framework and URL if the tergetUrl is not specific enough.

Assertion: The final step to a complete Open Badge is to publish an Assertion. This issuer uses hosted verification, so the Assertion is published at one of the allowed origins declared in the issuer Profile, yielding a canonical URI like https://example.org/beths-robotics-badge.json:

{
  "@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$b6877bb4361da770ac2c9fa2f28136de8dc93d823bbc1de438d5987e3f4032ef"
  },
  "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"
  }
}
  • The issuer has not chosen to implement the Evidence class to provide machine-readable descriptions of evidence in the Assertion itself. See an example that does.
  • The recipient’s email address beth@example.org is salted and hashed. The declared salt value deadsea is appended to the recipient email address. Hashing the string beth@example.orgdeadsea with the SHA-256 algorithm yields b6877bb4361da770ac2c9fa2f28136de8dc93d823bbc1de438d5987e3f4032ef. The sha256$ algorithm identifier is tacked on the beginning to form the identity reference in the Assertion.
  • 2.0 is more explicit about what types of identifiers may be used, but in this case, email is still the property used to identify the recipient. If a system trusted that the following profile was a match for a user account on their system, this Assertion could be trusted to have been awarded to that profile.
  • An expiration date is optionally included. Both issuedOn and expires use the ISO-8601 timestamp format and include a time zone designator (Z for UTC). Several other timestamp formats were previously accepted.

An example recipient profile matching the above badge would look like this:

{
  "@context": "https://w3id.org/openbadges/v2",
  "type": "Profile",
  "email": ["beth@example.org", "bethpersonal@example.com"],
  "url": "https://twitter.com/exampleBeth"
}

Unlike the above examples, this Profile does not have an id and may never be published for public consumption. It is an example of how an application can model a user on its system based on the properties it trusts to serve as recipient identifiers for that profile. In addition to viewing badges issued to either of the listed email addresses as congruent, this profile may also be connected to badges awarded to this user’s Twitter handle where the profile URI was identified and the url IdentityObejct type was used.

Next: Verification

As you can see, the new options are easy for issuing applications to implement if they are starting from a compliant 1.1 system. There are more significant upgrades required for verification workflows, but also more reliability, once we have solidified some of the key components of the verification ecosystem. Stay tuned for an upcoming post that goes into more detail on these topics.