Skip to content
This repository has been archived by the owner on Aug 22, 2019. It is now read-only.

Assertion Information for the Uninitiated

Jump to bottom
SueSmith edited this page Sep 29, 2014 · 16 revisions

Trying to get started with Open Badges but feeling a bit overwhelmed by the amount of technical information? Not to worry, this document will get you acquainted with one of the most important elements in Open Badges and a great starting place for getting to grips with the tech: the assertion.

The assertion is a fundamental building block in the badging ecosystem. An assertion represents a badge awarded to an earner. Each assertion therefore forms part of the picture an earner paints of their skills and achievements.

Assertions describe three things:

  • who a badge was awarded to
  • what that badge represents
  • who issued the badge

Assertions are relevant to issuers and displayers:

  • If you're planning to issue badges, you will create (and serve) an assertion for each badge awarded to an earner.
  • If you're planning to display badges, the assertion contains the data you will query, verify and output for each badge displayed from an earner's public collections.

Note: Some proposed changes to the assertion specification are currently under discussion. See these threads in particular:

Contents

TL;DR

Assertions - the essentials:

  • an assertion is a JSON file (or JWS) describing a badge awarded to an earner
  • assertions can be "signed" (a JSON Web Signature) or "hosted" (JSON file at a stable URL)
  • a badge issuer must create an assertion every time they award a badge
  • each assertion links to a badge class file
  • the badge class describes what the badge represents
  • each badge class links to an issuer organization (file describing the issuer)
  • an assertion can be "baked" (embedded) into a badge image
  • so that the earner can take their badge anywhere online
  • assertions include information for badge displayers to verify the award
  • assertions can be revoked by the issuer

For more detail and explanation, read on.

Assertion Structure

The structure and content of the assertion is vital to the success of any badging application and to Open Badges generally. You may have read the theory of why badges are valuable - assertions are ultimately responsible for implementing much of that in practice.

Open Badges aim to achieve a number of objectives - the assertion has to facilitate these, so has a lot of work to do. Assertion structure is determined by the specification.

Here are some of the main tasks we want our digital representation of an awarded badge to accomplish:

  • provide information about the skill or achievement earned
  • relevant to a variety of potential stakeholders
  • represent the identity of the badge earner
  • provide details of whoever issued the badge
  • facilitate verification of the earned badge validity
  • aid badge search and discovery
  • use an open, shareable format

How do we deliver this? Through the assertion structure - which must reflect these key characteristics.

Assertion Content

Let's look at the detail of badge assertion structure.

Three separate files define a functional assertion. They represent: the badge assertion; the badge itself; the issuer.

Badge Assertion → Badge Class → Issuer Organization
who earned what badge → what the badge represents → who awarded the badge

The badge assertion includes a link to the badge information, which in turn includes a link to the issuer information. Since issuing organizations and individual badges often repeat, this allows for reuse of the badge and issuer data.

The content of the assertion files is JSON-formatted, and the structure includes fields, objects and arrays. Assertions can be either signed or hosted as we'll see below.

Overview

  • BadgeAssertion
  • uid
  • recipient - IdentityObject:
    • identity
    • type
    • hashed
    • salt
  • badge - link to BadgeClass
  • verify - VerificationObject:
    • type
    • url
  • issuedOn
  • image
  • evidence
  • expires

  • BadgeClass
  • name
  • description
  • image
  • criteria
  • issuer - link to IssuerOrganization
  • alignment - array of AlignmentObjects
    • name
    • url
    • description
  • tags

  • IssuerOrganization
  • name
  • url
  • description
  • image
  • email
  • revocationList

Required fields are in bold.

Badge Assertion

The badge assertion contains information regarding a specific badge that has been awarded to a specific earner. The assertion connects to information about the badge itself and ultimately to who issued it.

Property Expected Type Description
uid Text Unique Identifier for the badge. This is expected to be locally unique on a per-origin basis, not globally unique.
recipient IdentityObject The recipient of the achievement.
badge URL URL that describes the type of badge being awarded. The endpoint should be a BadgeClass
verify VerificationObject Data to help a third party verify this assertion.
issuedOn DateTime Date that the achievement was awarded.
image Data URL or URL URL of an image representing this user's achievement. This must be a PNG image, and if possible, the image should be prepared via the Baking Specification.
evidence URL URL of the work that the recipient did to earn the achievement. This can be a page that links out to other pages if linking directly to the work is infeasible.
expires DateTime If the achievment has some notion of expiry, this indicates when a badge should no longer be considered valid.

Note: While the current specification indicates that the badge class should be represented in the assertion badge field as a URL, with the linked file including the badge class JSON, there is currently a proposal to represent the badge class as an inline object, rather than as a link: https://github.com/mozilla/openbadges-specification/issues/5

Identity Object

Being able to verify the identity of a badge earner is essential for the badge to represent a reliable measure of the earner achievement.

Property Expected Type Description
identity IdentityHash or Text Either the hash of the identity or the plaintext value. If it's possible that the plaintext transmission and storage of the identity value would leak personally identifiable information, it is strongly recommended that an IdentityHash be used.
type IdentityType The type of identity.
hashed Boolean Whether or not the id is hashed.
salt Text If the id is hashed, this should contain the string used to salt the hash. If this value is not provided, it should be assumed that the hash was not salted.

Verification Object

Verification works differently for signed and hosted assertions. In both cases, the issuer is responsible for providing the verification information.

Property Expected Type Description
type VerificationType The type of verification method.
url URL If the type is "hosted", this should be a URL pointing to the assertion on the issuer's server. If the type is "signed", this should be a link to the issuer's public key.

Assertion Example

{
  "uid": "f2c20",
  "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": 1359217910,
  "badge": "https://example.org/robotics-badge.json",
  "verify": {
    "type": "hosted",
    "url": "https://example.org/beths-robotics-badge.json"
  }
}

Badge Class

The badge class contains information about the badge itself (which can potentially be awarded to multiple earners). The badge class describes what the badge represents.

Property Expected Type Description
name Text The name of the achievement.
description Text A short description of the achievement.
image Data URL or URL URL of an image representing the achievement.
criteria URL URL of the criteria for earning the achievement. If the badge represents an educational achievement, consider marking up this up with LRMI.
issuer URL URL of the organization that issued the badge. Endpoint should be an IssuerOrganization
alignment Array of AlignmentObjects List of objects describing which educational standards this badge aligns to, if any.
tags Array of Text List of tags that describe the type of achievement.

Note: As with the assertion badge field, while the current specification indicates that the issuer should be represented in the badge class as a URL, with the linked file including the issuer organization JSON, there is currently a proposal to represent the issuer as an inline object, rather than as a link: https://github.com/mozilla/openbadges-specification/issues/5

Alignment Object

Badges can optionally align to educational or other standards.

Property Expected Type Description
name Text Name of the alignment.
url URL URL linking to the official description of the standard.
description Text Short description of the standard.

Badge Class Example

{
  "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": [
    { "name": "CCSS.ELA-Literacy.RST.11-12.3",
      "url": "http://www.corestandards.org/ELA-Literacy/RST/11-12/3",
      "description": "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."
    },
    { "name": "CCSS.ELA-Literacy.RST.11-12.9",
      "url": "http://www.corestandards.org/ELA-Literacy/RST/11-12/9",
      "description": " Synthesize information from a range of sources (e.g., texts, experiments, simulations) into a coherent understanding of a process, phenomenon, or concept, resolving conflicting information when possible."
    }
  ]
}

Issuer Organization

Describes the issuer of the badge - the value of a badge will be determined in part by who issued it (consumers such as employers/ college admin need to be able to access this information when evaluating an earner's badges).

Property Expected Type Description
name Text The name of the issuing organization.
url URL URL of the institution
description Text A short description of the institution
image Data URL or URL An image representing the institution
email Text Contact address for someone at the organization.
revocationList URL URL of the Badge Revocation List. The endpoint should be a JSON representation of an object where the keys are the uid for a revoked badge assertion, and the values are the reason for revocation. This is only necessary for signed badges.

Issuer Example

{
  "name": "An Example Badge Issuer",
  "image": "https://example.org/logo.png",
  "url": "https://example.org",
  "email": "[email protected]",
  "revocationList": "https://example.org/revoked.json"
}

Badge assertions can include additional properties - see the assertion spec for guidance.

Extensions

The Open Badges spec allows issuers to use additional data items in their assertions. A proposal is currently under discussion regarding standardization of these extensions. The following thread outlines the key considerations: https://github.com/mozilla/openbadges-discussion/issues/20

Assertion Format

Assertions can be hosted or signed.

A hosted assertion involves the assertion files being stored online with application/json content-type. The URL for a hosted assertion has to be stable, as this is the source used to retrieve and verify the data about the awarded badge.

A signed assertion is provided in the form of a JSON Web signature, which includes as its payload JSON representing the badge data. See the Issuer API for more.

Verification

Badge assertions can be verified both by checking for structural validity and using the verification data included within them. Verification is carried out using the URL included in the VerificationObject.

See the assertion spec for a step-by-step guide to verifying awarded badges.

For more on what's involved in being an issuer, see Open Badges Onboarding: Issuers and the Issuer Checklist.

Introduction

Issuing

Displaying

Tips and Resources

Clone this wiki locally