Assertion Specification Changes

Summary

With the 1.0 release of the OBI, the new assertion specification has been implemented. Details about the specification and implementation can be found on the assertions page.

Problems Addressed in the New Spec

Data URL support

Allow image fields to be data URLs, so it's one less thing for the issuer to host. This also prevents against 404s.

Normalizing data

"badge" and "issuer" shouldn't have to be repeated for every badge. By separating those from the main assertion we also reduce problems associated with mutability – for example, the issuer should be able to add new tags to the badge that A) apply retroactively to all previous badges issued, and B) don't require modifying the per-user assertion.

Discovery

By normalizing out the "badge" and "issuer" information, discovery becomes easier. If the issuer exposes all of the badge JSON objects, we are much closer to being able to spider that information to get a directory of all of the badges an issuer offers.

Signed assertions

This adds a verify structure to the assertion, which allows for a "signed" type, and a URL for public key discovery. Normalization also allows us to sign just the data that's relevant to a badge instance.

Scaffold future support for alternate identity systems

Email is a great identifier because it's inherently federated and relatively easy to verify, but we'd like to support alternative types of identification (IndieAuth for example). By making recipient an object that describes the user identity, with an explicit type field, we open up the possibility of supporting future identity systems.

Reduce reliance on backpack as source of truth

The previous assertion A) only supported hosted assertions and B) did not include the URL for the assertion in the structure itself. This required the assertion URL to be passed around out of band with the assertion itself, making verification more difficult.

Backwards Compatibility

A general rule for detecting whether an assertion is the v0.5.0 (old) assertion is:

If badge is a URL, it's the version described by this document. If it's an object, it's the old version. Anything else is invalid.

Rules for a transforming a v0.5.0 assertion to the version described in this document:

BadgeAssertion

• recipient is an object
  • identity is the original recipient value
  • type is "email"
  • salt is found at the root level
  • hashed is determined by whether or not identity has an "@" character in it.
• issued_on should be treated as issuedOn
• image should be the image from badge.image
• BadgeClass data is contained directly in the badge object
• All unqualified URLs should be qualified with the value in badge.issuer.origin
• verify is an object
  • type is hosted
  • url should have been received with the assertion.

BadgeClass

• All unqualified URLs should be qualified with the value in badge.issuer.origin
• Drop version field
• IssuerOrganization data is contained in badge.issuer

IssuerOrganization

• origin should be treated as url
• contact should be treated as email
• name should be the concatenation of the original name, a colon (":") and the original org.

Example transformation

Original

{
  "recipient": "sha256$2ad891a61112bb953171416acc9cfe2484d59a45a3ed574a1ca93b47d07629fe",
  "salt": "hashbrowns",
  "evidence": "/badges/html5-basic/bimmy",
  "expires": "2013-06-01",
  "issued_on": "2011-06-01",
  "badge": {
    "version": "0.5.0",
    "name": "HTML5 Fundamental",
    "image": "/img/html5-basic.png",
    "description": "Knows the difference between a <section> and an <article>",
    "criteria": "/badges/html5-basic",
    "issuer": {
      "origin": "http://p2pu.org",
      "name": "P2PU",
      "org": "Mechanical MOOC",
      "contact": "admin@p2pu.org"
   }
  }
}

---

BadgeAssertion

{
  "recipient": {
    "type": "email",
    "hashed": true,
    "salt": "hashbrowns",
    "identity": "sha256$2ad891a61112bb953171416acc9cfe2484d59a45a3ed574a1ca93b47d07629fe"
  },
  "badge": <url-of-badgeclass>,
  "evidence": "http://p2pu.org/badges/html5-basic/bimmy",
  "expires": "2013-06-01",
  "issuedOn": "2011-06-01",
  "verify": {
    "type": "hosted",
    "url": <received-with-assertion>
  },
}

BadgeClass

{
  "name": "HTML5 Fundamental",
  "image": "http://p2pu.org/badges/img/html5-basic.png",
  "description": "Knows the difference between a <section> and an <article>",
  "criteria": "http://p2pu.org/badges/html5-basic",
  "issuer": <url-of-issuerorganization>
}

IssuerOrganization

{
  "name": "P2PU: Mechanical MOOC",
  "url": "http://p2pu.org",
  "email": "admin@p2pu.org"
}