Assertions

Assertions

Signed

In the future we will support signed assertions, which will mean signing a badge assertion with your private key and hosting a public key at a well known, public URL. In the even more distant future, we will probably try to support DNSSEC for public key discovery. For now, we only support Hosted Assertions.

Hosted

A hosted assertion is a file containing a well-formatted badge assertion in JSON served with the content-type application/json. This should live at a stable URL on your server -- it is the source of truth for the badge and any future verification attempt will hit that URL to make sure the badge exists and was issued by you.

Setting Content-Type

In the examples below badge_assertion is a native dictionary, hash or associative array. badge_assertion_json is a prepared JSON string.

PHP

// Do this before doing anything that starts a response
header('Content-Type: application/json');

Drupal 6

// do not use drupal_json -- it sets the wrong header
drupal_add_http_header('Content-Type', 'application/json');
echo drupal_to_js(badge_assertion);

Drupal 7

drupal_json_output(badge_assertion);

Django

HttpResponse(badge_assertion_json, mimetype='application/json')

Rails

render :json => badge_assertion

Apache

# Save your assertions as .json files and add this to your httpd.conf
AddType application/json        json

Nginx

# In your server context, add the following:
types {
  applications/json     json;
}

Example assertion (with optional fields)

{
  "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": "School of Webcraft",
      "contact": "admin@p2pu.org"
   }
  }
}

NOTE: If a URL is not fully-qualified, the issuer.origin will be prepended to resolve it.

Field Descriptions

Required

• recipient: Salted hash of the user's email address. Takes this form: <algorithm>$<hash(email + salt)>. We recommend using sha256, but we also support sha512 and md5.
• salt: The salt used in the above hash construction.
• badge: The structure describing the badge.
  • version: The version of the spec/hub this manifest is compatible with. Use "0.5.0" for the beta.
  • name: Human-readable name of the badge being issued. Maximum of 128 characters.
  • image: URL for image representing the badge. Should be a square and in PNG format. Maximum size of 256kb.
  • description: Description of the badge being issued. Maximum of 128 characters.
  • criteria: URL describing the badge and criteria for earning the badge (Not the specific instance of the badge).
  • issuer: Information about the issuer:
    • origin: Origin of the issuer. This is the <protocol>://<host>:<port>. Must match the origin of the hosted assertion (and in the future, the origin of the public key).
    • name : Human-readable name of the issuing agent.
    • org: (OPTIONAL) Organization for which the badge is being issued. Another example is if a scout badge is being issued, the "name" could be "Boy Scouts" and the "org" could be "Troop #218"
    • contact: (OPTIONAL) A human-monitored email address associated with the issuer.

Optional

• evidence: User-specific URL with information about this specific badge instance. Should contain information about how the specific user earned the badge.
• expires: Date when the badge expires. If omitted, the badge never expires. The badge is not removed from the user's backpack after the expires date – there will be some visual/technical indicator that the badge is expired and needs to be re-upped. Must be formatted YYYY-MM-DD or a unix timestamp
• issued_on: Date when badge was issued. If omitted, the issue date will be set to whenever the hub received the badge. Must be formatted YYYY-MM-DD or a unix timestamp

NOTE: We've discussed having an additional field that is customizable by the user - so that the user could add a personal evidence URL, or could add additional information or context to the badge. This would NOT be something that they issuer would include in the badge manifest (so it is not listed above) and would most likely be managed by the user through the Backpack.