Creating Badges Manually

If you’re an organisation or individual who is teaching a measurable skill, you might want to create a badge as a trophy for individuals who have completed your training.

The process takes five steps: The high-level overview:

1. Create a graphic for your badge
2. Create an “assertion” file for your badge
3. Upload the files to your web server
4. Combine the text file and graphic into one file
5. Distribute!

It’s important to note that there are less-manual ways of creating, hosting, and awarding badges, but using an automated service without understanding the technology that they are employing sometimes makes the process more complex instead of simpler.
Right now, badges are still new; and sometimes the badges you create in one service do not play well with other badge services online. So we at Makerbox just do it manually.

Step By Step

And here is the badge creation process detailed, step-by-step:

1. Create a graphic for your badge

Grab either GIMP or Inkscape (or any of the myriad free graphic applications out there) and draw an attractive badge design. Badges should be roughly as tall as they are wide, because when you export it, it must be in a square canvas. To make sure you’re using a square canvas in GIMP, go to the File menu and select New, and fill out the requirements for a new square canvas:


To do this in Inkscape, go to the File menu and select New > CD Cover. Use the CD Cover preset because CD covers are square. When exporting the image:


512×512 is large enough for most uses, and since badges must be under 250 kb, it’s wise to keep things small.

Since you can’t be sure what size a badge is going to be displayed at, a simple design is probably better than a very complex, busy design, but let your own creativity be your guide.

If you don’t feel that you have great graphic skills, use pre-fab graphics from or the Wiki Commons and just throw some stuff together! Feel free to download and use MakerBox’s Inkscape badge template.

2. Create an assertion file for your badge

In order to verify that a badge was given from an organisation and isn’t just a graphic that someone uploaded to their website, badges must be issued and self-registered. There is no centralised authority for badges, so self-registration of badges provides accountability for the organisations issuing them.

Assertion files must be formatted and saved as a JSON file. Create your assertion file in a plain text editor. Frequently, the text editors that ship with commercial operating systems cannot save as plain text, so using a text editor specifically designed to save code files will make your life a lot easier. Try gedit. If you’re running Linux, gedit (or a similar plain text editor) is probably already on your system.

A sample assertion file:

“recipient”: “”,
“evidence”: “”,
“issued_on”: “2014-06-26″,
“badge”: {
“version”: “1.0.0″,
“name”: “Programming Apprentice”,
“image”: “”,
“description”: “The earner of this badge blah blah blah.”,
“criteria”: “”,
“issuer”: {
“origin”: “”,
“name”: “MakerBox”,
“org”: “MakerBox”,
“contact”: “” } }

  • recipient: the email address assigned to a valid badge Backpack of the recipient
  • evidence: a link to a webpage supporting the badge’s value
  • issued_on: a date in the format year-month-day or as seconds from the Unix epoch
  • version: a version number for your badge (just make something up)
  • name: the name of your badge
  • image: a link to the png file of your badge
  • description: your description of what your badge signifies
  • criteria: a link to a webpage detailing the requirements for earning your badge
  • origin: a link to your website
  • name: your name
  • org: the name of your organisation
  • contact: an email address for who can be contacted about the badge

Note that the format is of ultimate importance. An improperly formatted JSON file cannot be read, so make sure you have all the punctuation correct.The JSON spec is quite strict; for example:

  • Every quotation mark, comma, colon, and brace matters!
  • All websites must be prefixed with “http://”.
  • You must not use quotation marks inside of quotation marks; use single quotes instead.

To make sure your JSON file is valid, go to and paste in the text of your assertion file. It will alert you of any errors it may contain.

3. Upload the files to your web serve

Upload both the badge graphic and the assertion file to your web host. If you do not have a web host, you can use any web service that provides a publically share-able link, like Dropbox or Google Drive or even imgur and Fedora Pastebin. Alternately, get a free Unix shell at and use that as your host.

If you do have a web hosting account, use FileZilla or SSH to upload your files to your account.

4. Combine the text file and graphic into one file

To finalise your badge, you must “bake” the PNG and the JSON assertion into one single file. Mozilla provides an online service to make this easy at

The easiest and best way to use this is to just type into the URL bar of your browser (assuming that is the location of your assertion file, in this example).

If you are processing multiple badges for a whole class of students, you can script this process by sending that link via wget or curl in a terminal.

The site will silently process your assertion and graphic file, and then ask you what you’d like to do with the new baked PNG file that you’ve just created. That file, my friend, is your badge. Download it and save it.

5. Distribute!

Now that you have your badge file, you can give it to its intended recipient by either emailing it to them or posting it online for them to download.

The recipient can download the badge file to their computer and import it into their badge backpack. There are many backpack services online but probably the best and most reliable one right now is Mozilla’s Backpack.


What do you think?

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s