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

Badge Baking

Jump to bottom
Sue Smith edited this page Jan 19, 2015 · 33 revisions

A baked badge is a badge image with assertion data embedded in it. If you're new to assertions, see Assertion Information for the Uninitiated and the assertion specification - otherwise, read on.

Issuers use assertions to represent the badges they have awarded to earners. Each badge assertion includes an image file for the badge and some metadata describing the earner, their awarded badge and the issuing organization.

Issuers can bake the assertion data into the badge image, so a baked badge provides/ links to all of the descriptive and verification data about that awarded badge instance. Software with an awareness of the Open Badges structures can extract the metadata from a baked badge and parse it.

You can bake a badge in various ways, including:

  • the baker API within the Mozilla hosted Backpack
  • the openbadges-bakery tool
  • can be used in a Web browser, on the command line or within application code

If you use the Issuer API to push earner badges to the Backpack, it will handle baking the badges for you.

For a detailed overview of the structures used in a baked badge, see the Badge Baking specification. For PNG badges, baking involves inserting an iTXt chunk with the keyword openbadges - the text is the badge assertion JSON or signature. For SVG badges, baking involves adding an openbadges element to the markup code - the element includes the assertion being baked.

Local Baking

Fortunately, the PNG specification isn't very complicated, and libraries exist in many languages to easily manipulate them, so you can bake a badge locally using a technology of your choice.

Open Badges Bakery

The openbadges-bakery tool is a node module for baking badges, which you can use locally on the command line or in your own applications. The tool works for signed and hosted badge assertions, and for both PNG and SVG images.

You can install the bakery using Node Package Manager as follows:

npm install openbadges-bakery

Command Line

Baking

You can use it on the command line as follows:

oven [--in ./path/to/image.svg] [--out ./path/to/baked-image.svg] <data>

This takes an image and writes the assertion data into it, writing the result out to the specified file. So, presuming you were in the node_modules/openbadges-bakery directory and had an image in the same directory that you wanted to bake:

bin/oven --in badgeimage.png --out bakedbadge.png '{"uid": "123456789abcdefghi987654321jklmnopqr", "recipient": ...}'

This would bake the included assertion JSON into "badgeimage.png", writing the baked version out to "bakedbadge.png".

Extracting

To extract the assertion data from an existing baked badge:

oven [--in path/to/image.png] --extract

For the above example, you could extract from the baked badge you created:

bin/oven --in bakedbadge.png --extract

The terminal should write out the assertion JSON.

Library Usage

If you want to build badge baking and/or extracting into a Web application, you can use the bakery library. To use it in a node.js app, you could take the following approach:

var bakery=require('openbadges-bakery');

Baking

Then to bake an image with assertion data you could do something like this:

app.get('/bake', function(req, res){
	//prepare the assertion and image
	var img=fs.readFileSync('thebadge.png');
	var theAssertion ={
		"uid": "123456789abcdefghi987654321jklmnopqr",
		"recipient": {
			"identity": "sha256$98765edcba98765edcba98765edcba",
			"type": "email",
			"hashed": true
		},
		"badge": "http://issuersite.com/badge",
		"verify": {
			"url": "http://issuersite.com/assertion",
			"type": "hosted"
		},
		"issuedOn": 1403120715
		};
	var options = {
		image: img,
		assertion: theAssertion,
	};
	//bake assertion into image
	bakery.bake(options, function(err, data){
		//give the baked badge a file name
		var fileName = 'newbake.png';
		var imagePath = __dirname+"/baked/"+fileName;//"baked" directory
		//write the returned baked badge data to file
		fs.writeFile(imagePath, data, function (err) {
			if(err) res.send(err);
			else res.send("<img src='"+imagePath+"' alt='badge'/>");
		});
	});
});

This example uses assertion JSON for a hosted badge, but you can use the bakery to bake signatures into your badges too. Here we provide the image and assertion data, calling on the bakery to bake it into the badge. The bakery returns the baked badge image data, which we then write out to file and output to the Web page.

Extracting

If you want to extract the data from a baked badge image in a node app using the bakery, you can take the following approach:

app.get('/unbake', function(req, res){
	var img=fs.readFileSync('baked/newbake.png');
	bakery.extract(img, function(err, data){
	res.send(data);
});

This takes the baked badge we wrote out in the baking example above, extracting the raw data from it and writing it to the page. Note that the raw baked data may be the assertion JSON, a URL for the assertion or a signature. To get the assertion data directly without carrying out further processing, you can use the following alternative:

app.get('/unbake', function(req, res){
	var img=fs.readFileSync('baked/newbake.png');
	bakery.getAssertion(img, function(err, data){
	res.send(data.uid);
});

If the assertion is remote, this code will create a request for it. The assertion is returned as an object, so in this case we write out the uid for demonstration - your code can access any of the assertion fields directly in this way.

Baking SVGs

If you use SVG badges, you can use the OBI bakery tools. However, the task of baking with SVG badges is so straightforward you may prefer to implement it within your own applications, rather than relying on other tools.

To bake data into an SVG, all you have to do is embed some additional markup code. First, your svg element needs the following attribute:

xmlns:openbadges="http://openbadges.org"

Then, as a child of the svg element, the assertion data:

<openbadges:assertion verify="https://example.org/assertion.json">
    <![CDATA[
       {
         "uid": "abcdef12345",
         "identity": {
           "recipient": "sha256$cbb08ce07dd7345341b9358abb810d29eb790fed",
           "type": "email",
           "hashed": true
         }
         "verify": {
           "type": "hosted",
           "url":"https://example.org/assertion.json"
         }
         "issuedOn": "2013-11-05",
         "badge": "https://example.org/badge.json"
       }
    ]]>
  </openbadges:assertion>

The verify attribute should either contain the location of a hosted assertion (which should also be in the verify.url field) or the signature for a signed assertion.

The body of the openbadges:assertion element should be the assertion JSON wrapped in CDATA tags for a hosted badge. For a signed badge, the openbadges:assertion element should be empty, as the signature in the verify attribute will contain the assertion data.

As you can imagine, you could both bake and extract the data from SVG badges in your own applications with a minimal amount of code. For more, see Using SVG Badges.

Using the Baking Service REST API

The Backpack repo documentation contains an overview of using the Badge Baking API.

Essentially, to use the baker API, send a GET request to:

http://backpack.openbadges.org/baker?assertion=http://yoursite.com/badge-assertion.json

...passing the URL for the assertion you want to bake. The assertion should include a link to the badge class, which should include an image field which is the URL of the badge image. The baker will retrieve this image and bake your assertion data into it, returning it to you if your API call was successful.

Baking Process

  • The baker will execute a GET request on the assertion URL you pass as parameter, checking it for validity first.
  • You may wish to validate your assertions before attempting to bake them with the API.
  • If the assertion is well-formed, the baker will then carry out a GET request on the badge image URL.
  • Each GET request will be preceded by a HEAD request to ensure existence and reasonable response size.

Baking Options

Historically, the baking tools have used a few different approaches you may need to bear in mind when handling baked badges. Baked badges may have the assertion URL or the assertion JSON embedded into them. Additionally, the assertion badge and badge class issuer fields, under the current specification, will have the URLs for separately hosted JSON files. However, a proposal is currently under discussion to allow inclusion of these as JSON objects rather than separate files.

See these threads for more info on developments in the baking process:

Baked Badge Display

If you are looking to display baked badges in a Web page, the Open Badges Displayer automates presenting the metadata in an interactive component using only client-side code.

Introduction

Issuing

Displaying

Tips and Resources

Clone this wiki locally