A Guide to Writing Open Badge Metadata

This wiki page is meant to guide authors of new open badges in the writing of open badge metadata. It describes the three metadata classes of the Open Badges 2.0 standard from IMS Global. It also describes the metadata fields within each data class and offers suggestions for how to author metadata for each field.

Metadata

Metadata is data that describes other data or information. For example, when you take a picture with your smartphone, your phone records additional data such as when (and possibly where) the picture was taken, how big the image file is, and who the author is. That additional data is called ‘metadata’.

Open badges also contain metadata. The Open Badges 2.0 specification is the rulebook that tells us how to write metadata for open badges so that other people and even computers can read and understand it. The Open Badges 2.0 standard identifies three main types of data related to open badges, called data classes, that need to be described by metadata: Badge Classes, Assertions, and Profiles. 

Badge Class

A Badge Class is the formal description of a badge and contains information that will be common to everyone who earns that badge, e.g. badge name, the badge image, badge description, criteria to earn the badge, alignment to standards, tags, and general expiry information. Think of a badge class as the mold that is used to cast all the unique assertions (i.e., instances) of a badge that can be earned by individuals.

Badge Name

The Badge Name is a required field. This is the name of the badge. The Badge Name should be short and the content of the achievement should be easily understandable. Keep in mind that the Badge Image and Badge Name are typically the first things a badge consumer will see, and together the name and image should be capable of providing a sense of what the badge is about.

Examples:

• Business Meeting Etiquette
• Decision Making in Teams
• Conference Presenter

Description

The Description is a required field. A Description is a short explanation of the claim being made by the badge and a brief overview of what a recipient must do to earn the badge. When badges are listed, shared, or displayed, the Descriptions can be read by badge consumers, e.g., employers, as well as by learners who are considering earning the badge. Succinct descriptions, perhaps slightly longer than “tweet length,” may be more effectively shared via social media.

Although there are somewhat different categories of badges, a good badge description will briefly describe as many of the following badge characteristics as are relevant:

• It should describe the context in which the badge was earned.
• It should specify the achievement.
• It should refer to completed tasks.
• It should explain the assessment procedures.

Image

The Image is a required field. Images should conform to the following specifications.

• PNG or SVG file type
• Images should be square (equal width and height)
• Image file size should not exceed 256k
• Image dimensions should be no smaller than 90 x 90 pixels
• Recommended image size varies by badging platform. For PNG files, most recommend an image size of 400 x 400 – 600 x 600 pixels.

The following are style considerations when designing your badges.

• The badge image, together with the badge name, are typically the first thing badge consumers will see, and together the name and image should be capable of providing a sense of what the badge is about.
• The badge image may contain issuer branding. However, because badges can be displayed at sizes as small as 90 x 90 pixels, take care that branding remains legible/visually appealing.
• Your Badges may be displayed at different sizes. You should Preview your image at around 90x90 device pixels to ensure that elements are clear. This is around the smallest size that applications commonly embed badge images on the web .
• Badges are portable and may be displayed in a variety of digital contexts and against different background colors.

If you have the option, please add “alt text” so that your badge image is accessible to all users.

For additional guidance on open badge images, see Badgr’s resource “What are the recommended specifications for badge images?”

Issuer

The Issuer is a required field. The Name of the issuer is a name of the individual, entity, or organization that issued the badge. If you are using a badging platform to issue badges, you will most likely provide your Issuer information when setting up an issuer account.

Criteria

Criteria is a required field. Criteria list all of the detailed requirements that a badge earner had to meet in order to earn a given badge. Criteria are written for potential badge earners to provide them with as much specific detail as they need in order to earn the badge. Criteria are also written for badge consumers to provide a detailed account of exactly what badge earners had to do to earn a particular badge. If there is an assessment rubric associated with the badge, consider sharing it here.

• A badge may be associated with multiple criteria
• Criteria can be required or not
• Criteria should be associated with a description and indication of acceptable evidence.
• The criteria should be exhaustive, i.e., they should include all requirements needed to earn the badge.
• If your badge is associated with a competency-based assessment, the badge criteria should align very tightly with the competency statement.
• Criteria can also specify the type of evidence needed to earn the badge. For example, a badge may require potential recipients to submit writing, record video of themselves demonstrating a skill, or submit proof of having attended an event.

As much as possible, badge criteria should follow the SMART acronym. That is, criteria should be…

• Specific: what will the badge earner have accomplished by earning this badge?
• Measurable: how will the assessor know when the level at which the badge is awarded has been achieved?
• Achievable: in what ways can the badge be achieved?
• Relevant: is this badge worth earning? what opportunities does it unlock?
• Timely: should this badge expire after a certain period of time?

For more guidance on writing metadata for the Criteria field, see WeAreOpen.Coop’s resource “How can I create effective Open Badges?”

Alignment

The Alignment field is optional. The alignment field enables a badge to be aligned to recognized academic or professional standards. A badge aligned to recognized standards is easier for badge consumers (e.g. hiring managers) to find and understand, which adds value for badge earners, consumers, and issuers.

The contents of the Alignment field should consist of a URL/URI that points at an element of an educational or professional standard, or at a competency definition used by multiple organizations.

Tags

The Tags field is optional. Tags are alternate terms or phrases to describe the badge’s topics, competencies, or type of achievement. Tags are intended to help badge consumers and potential badge earners find relevant badges. As such, the tag field should contain as many relevant keywords as will be helpful.

Examples of tags may include but are not limited to: programming, open-source, bitcoin, volunteer work, hand-crafted, dogs, space, and many others.

Expiry Date

The Expiry Date filed is optional. If the achievement has some notion of expiry, this indicates a timestamp when a badge should no longer be considered valid. After this time, the badge should be considered expired

Assertion

Badge Assertions are the unique instances of a badge that individuals earn. In other words, an assertion is the actual digital credential, or claim, that the earner receives and that serves as the record of their achievement. In addition to containing all the general information of the badge class, the assertion contains all the information that makes it a unique instance of the badge, e.g., the identity of the badge recipient, and optionally a link to evidence, a narrative, and an expiration date. 

Date Issued

The Date Issued field is required. This is the date the badge is issued (as the name suggests). Most badging platform, e.g. Badgr or Credly, should take care of this for you.

Evidence

The Evidence field is optional. The evidence field contains evidence of an accomplishment that is (or at least can be) unique to each badge assertion. Whenever possible, the Evidence field should include links to documents, videos, images, or other artifacts that support the badge’s claim about the recipient’s accomplishment. Such evidence makes a badge earner’s claim more credible.

The Evidence field can also include textual evidence. When entering text in the evidence field, please don’t simply repeat what’s already in the Criteria field. Instead, provide specific and unique details about how a particular recipient earned the badge. For example, provided you have the recipient’s permission and are not violating privacy, you might use the Evidence field to share an earner’s score or evaluator’s feedback. One might use the Evidence field to describe an earner’s particular contributions to a project, or describe what the earner did during an event.

Narrative

The Narrative field is optional. Whereas the Evidence field lists and describes distinct bits of evidence supporting a badge’s claim, the Narrative field provides an overarching description of how a badge was earned. Again, please don’t repeat what’s already in the Criteria field. Instead, provide specific and unique details about how a particular recipient earned the badge.

If a badge uses multiple pieces of evidence to support its claim, the Narrative field may be used to describe how the multiple/various pieces of evidence relate to one another and support the badge’s claim.

The narrative field supports the use of Markdown, which can enhance text by enabling elements e.g. links, emphasis, and lists. However, be aware that open badge displayer tools do not yet evenly support Markdown.

Profile

A profile is a collection of information about the person or organization that is using open badges. Profiles can be associated with badge issuers, badge recipients, and endorsers. Metadata for this data class will likely have already been provided when you created your account with a badging platform.