Open Badges Onboarding: Displayers
Open Badges displayers present earner badges within digital contexts such as applications, websites and widgets. If you want to get started as a badge displayer, this document will introduce you to the key concepts and technologies involved.
- TL;DR
- Who's Involved
- What does a Displayer do?
- Open Badge Infrastructure
- Concepts
- Open Badges
- Assertions
- Badge Issuing
- Badge Display Tasks
- Retrieving Badges
- Verifying Badges
- Requirements
- Resources and Next Steps
Badge display essentials:
- badge displayers can retrieve earner badges from a source such as the Mozilla Backpack
- earners control which badges are public
- badges are associated with an earner email address
- displayers present earned badges in digital contexts
- displayers handle the assertion data for badges
- this is the metadata describing an awarded badge
- describes the earner, what the badge represents and the issuer
- is structured in JSON
- displayers can present selected data items from the assertion alongside the badge
- some displayed badges are "baked"
- this means that the assertion data is embedded into the image
- displayers sometimes need to validate and verify badges
- this means checking that a badge is legitimate and structurally valid
For more detail and explanation, read on.
Open Badges projects and applications can involve a range of individuals and organizations. The key participants are:
- earners
- issuers
- displayers
- consumers
Issuers create, publish and award the badges to earners. Displayers present an earner's badges in a digital context. Although not directly involved with the badging lifecycle, consumers are other people who might have an interest in an earner's badges (e.g. an employer or college admin).
A displayer outputs a visual representation of the badges an earner has been awarded. This involves:
- retrieving and parsing the badge JSON data
- verifying the validity of each badge
- including elements of the badge metadata for viewing
The badge data you retrieve as a displayer will originally have been created by a badge issuer. Issuers define a badge that is available for earning as a badge class. When an earner is awarded a badge, the issuer creates a badge assertion representing the award. The assertion includes a link to the badge class, which in turn includes a link to information about the issuer (which could be a person or an organization such as a school).
Displayed badges may be viewed by various third parties referred to as consumers.
The Open Badge Infrastructure (OBI) is a range of specifications, technologies and tools which support the badging ecosystem. It includes APIs and software to aid the process of adopting Open Badges within your own environment. There are many Open Badges projects on GitHub - the following repos are of particular relevance to displayers:
Before we move on, let's make sure we have a clear understanding of a few key concepts you will encounter throughout the Open Badges projects.
An Open Badge is a digital representation of a skill or achievement. Each badge awarded to an earner comprises a digital image file and some metadata. The metadata describes what the badge represents, the identity of the earner and the issuing organization. The metadata conforms to the structure defined within the Open Badges specifications, which you can see on GitHub: https://github.com/mozilla/openbadges-specification
The specifications help to define the standards that guide Open Badges' creation and use. A range of technology projects also support badging - developed by Mozilla and a network of partner organizations including those in the Badge Alliance.
As a displayer, one of the key aspects of Open Badges you will be involved with is the assertion. An assertion represents a specific badge awarded to a specific earner. Think about a badge you process as a displayer - it includes a series of data items describing what the badge represents. The badge may potentially be awarded to multiple individual earners - we need a way to represent these badge instances in contrast to the generic representation of the badge: this is where the assertion comes in.
An assertion includes all of the information we need to implement the value of an Open Badge:
- the earner identity
- what the badge represents
- who issued the badge
Each assertion is represented as an image and three JSON metadata files: the badge assertion; the badge class; the issuer organization.
The badge assertion describes the specific instance of the badge awarded to the earner email address - and includes a link to the badge class. The badge class describes the generic badge which may be awarded to multiple earners - and includes a link to the issuer organization. The issuer organization includes data about whoever issued the badge.
The badge metadata can be embedded into the badge image file - this is referred to as a baked badge.
Assertions can be hosted (stored as hosted files) or signed (JSON Web Signatures).
To display badges, you need some familiarity with badge assertion structure - see these pages for more:
To understand the displayer role, it's worth getting to know the basics of what's involved in the issuing process. Issuers decide which badges to award and who to award them to. Since the purpose of a badge is to represent a recognized skill or achievement, earners also need a way to show their badges to others. One way of facilitating this is for the issuer to offer to push awarded badges to the Mozilla Backpack, where the earner can manage them within groups. Earners can decide to make a group public, which allows displayers to retrieve the badges within that group given the earner email address. Displayers may also present badges from other sources.
As we've explored, displayers can retrieve badge data from a variety of sources depending on the badge issuer and the earner choices. How the displayer processes a badge will be determined in part by how they retrieved it and what form its assertion takes.
As a displayer, you may receive the information about earner badges from a variety of sources, including the Mozilla Backpack. If you retrieve badges from the Mozilla Backpack, you can use the Displayer API, passing the earner email address and receiving a JSON response including the data you will need to write the earner's badges into your site, application or widget output code. If you're receiving badge data from another source, the data you will be dealing with will either be a hosted badge assertion file (stored at a particular URL) or a JSON Web Signature representing the badge.
As a displayer, you can carry out a range of verification checks to ensure the validity of badges before you display them. In order for an Open Badge to comprise a valuable representation of the earner's skills and achievements, consumers have to be able to trust the legitimacy of the displayed badges they see - the displayer is ultimately responsible for implementing this.
If you are using the Displayer API, you do not need to verify the badges, as the Mozilla Backpack does this when the badges are imported. If you aren't using the Displayer API and are implementing your display application in node.js, you can use the openbadges-validator to carry out verification in a few lines of code. Otherwise, you will need to implement verification in your application code.
Verification can involve:
- checking badge JSON structure
- unpacking and verifying a JWS with a public key (if signed)
- checking that the assertion is available at the stated URL (if hosted)
- checking that the badge class linked to is available at the stated URL
- verifying the earner email (which may involve hashing/ generating a salted hash)
- checking that a badge has not been revoked (using revocation list if signed)
See Verifying Badges for Display for more.
To display badges you need:
- a Web server able to make Internet requests
- ability to make a
GETrequest and read a JSON response - access to the earner's email address
- which should be converted to their ID if using the Mozilla Backpack
If you are displaying baked badges, you can use the Open Badges Displayer script to present an interactive component using only client-side code.
For additional support:
- Post general questions in our Community Google Group and post technical questions in our Dev Google Group.
- Reach members of the Open Badges team directly on IRC (irc.mozilla.org) on the #badges channel.
- Email questions directly to badges@mozillafoundation.org and a member of the team will follow-up.
- Follow or tweet the Open Badges team @OpenBadges.
- Get involved or submit issues via the GitHub repos - feedback is always appreciated!