BMPR File Format Reference

Overview

At the heart of all Balsamiq projects are BMPR files. BMPR files (short for Balsamiq Mockups PRojects) are a type of BAR file. BAR files, or Balsamiq Archive files, provide a way a storing different kinds of content while also providing a consistent set of tools for reading and writing that content.

BAR is a format for files that have resources of various types, branches, and thumbnails. For instance, one could build the next Keynote, Visio, or Photoshop using BAR as its file format. Our hope is that some day someone might want to adopt the format. If not, we’ll probably adopt it ourselves for our next product.

In other words, BMPR files are a kind of BAR file. All BAR files share similar APIs describing what kind of content the archive contains.

In the case of BMPR files that content contains everthing there is to know about a Balsamiq project.

Getting a BMPR File

If you want to get your hands on a BMPR file, create a new wireframe using Balsamiq app and save the file somewhere. That’s a BMPR file. Or download the example used for creating some of the documentation that follows.

The BMPR format isn’t the first format we’ve used for Balsamiq. For example, in the past we’ve used BMML. A Mockups 2 project requires multiple BMML files making them a little more cumbersome to manage. A single BMPR file contains everything for a project. This single file approach makes sharing projects much easier.

Who Is This For?

It’s for you and for all the other people who are making tools that integrate with Balsamiq!

Maybe you’re curious about how your projects are stored. Maybe you want to make tools that can read the files or even generate BMPR files programmatically. Maybe you want to teach a robot how to draw your wireframes using chalk on sidewalks. We hope that happens!

Versions

The current version of the BMPR file format is 1.2.

We use Semantic Versioning (SemVar for short) for the BMPR file format. This means, among other things, that the API for version 1.2 of the file format won’t change. New minor versions can change the API but will remain backwards compatible with previous versions. Major versions such as a 2.0 release will be incompatible with previous major versions.

Version 2.0 of the BMPR file format is already being worked on and will not be compatible with previous major versions. 2.0 might be the same in some ways, but it’s best to assume it’s not 100% compatible with 1.x versions. When version 2.0 of the format is released we’ll update this reference to make the differences between versions clear.

When writing tools for the BMPR file format it’s a good idea to ensure that your tools are aware of version differences. BMPR files are a type of BAR file, and all BAR files contain both the file format type (such as bmpr) and the version (1.2) that file format uses. Examples of how those details are stored can be found in the INFO section below.

Details

A BMPR file is a humble SQLite database file that stores both scalar values (single numbers, strings, etc) and JSON data that describes every detail of a Balsamiq project. Using SQLite enables BMPR files to take advantage of the huge amount of historical experience, tools, and libraries for reading and writing to relational databases while also being very portable and embeddable.

Here’s what a BMPR file looks like when opened using the free DB Browser for SQLite app:

There are 4 tables in a BMPR file:

  • INFO contains details about what kind of resources an archive contains
  • RESOURCES is where most of the content found in a project lives
  • BRANCHES contains information about branches in a project
  • THUMBNAILS has entries for wireframe thumbnails

The INFO Table

The INFO table describes what kind of data, or resources, our file contains. BMPR files are a kind of BAR file, and BAR files use the INFO table to describe what kind of data they contain. It allows developers to inspect an archive file so they can make informed decisions about how to handle the content within.

Table Fields
Field Datatype Description
NAME TEXT The unique name of the kind of meta data for this row. Think of this as a you would a key in structure or hash.
VALUE TEXT The value for this meta data entry
Example Data
NAME VALUE
SchemaVersion 1.2
ArchiveRevision 44
ArchiveRevisionUUID 007F035B-6147-D643-C5CC-2871D9DA1C43
ArchiveFormat bmpr
ArchiveAttributes
{
  "creationDate":1467124505618, // the date this archive file was created
  "name":"banking_interface"    // the name of the resource
}
SchemaVersion

This is the file format version number for the kind of resource this archive contains.

ArchiveRevision

This contains a count of how many times this archive file has been changed.

ArchiveRevisionUUID

This is a unique ID that identifies the latest revision of this archive.

ArchiveFormat

This indicates what kind of data this archive contains (for example, bmpr).

ArchiveAttributes

This is a JSON hash containing the creation date of the file as well as a name for the contents of this archive.


The RESOURCES Table

Details about wireframes, assets, and symbols are stored here. Each row in this table contains details (coordinates, shape, and size, etc.) about every element in a project.

Table Fields
Field Datatype Description Example
ID TEXT

A unique id for a resource

ADC6E183-B52E-038A-1BBC-DAEDBAE75554
BRANCHID TEXT

The branch this resource belongs to

Master
ATTRIBUTES TEXT

JSON data with keys for creationDate, thumbnailID, kind, modifiedBy, notes, mimeType, order, name, importedFrom, parentID, and trashed

Example:

{
  "creationDate": 0,                    // the date this resource was created
  "importedFrom": "",                   // for imported resources this will be the original file name of that resource
  "parentID": "",                       // a unique ID that, when present, associates this resource with another resource
  "kind": "mockup",                     // the kind of resource this row describes
  "mimeType": "text/vnd.balsamiq.bmml", // the mime type for this resource
  "modifiedBy": null,                   // who (or what) last modified this resource
  "name": "Banking Website",            // the name of this resource
  "notes": "",                          // notes for this resource
  "order": 2445916,                     // an absolute integer representing this resource's position
  "thumbnailID": "[UUID]",              // the unique ID of the thumbnail for this wireframe
  "trashed": false                      // a boolean flag indicating if this is a trashed resource
}
The order key is only present when the resource is a mockup.
DATA TEXT

JSON data with keys for wireframe data. See below for more details.

If the resource is a kind of otherAsset or asset the data stored for this resource will be the Base64 encoded representation of the asset.

 

Example:

{
  "mockup": {
    "controls": {        // an array containing each element (see more about this below)
      "control": ["..."] // JSON data with properties unique to the control type
    },
    "measuredH": "600",  // the pixel height of the wireframe
    "measuredW": "800",  // the pixel width of the wireframe
    "version": "1.0"     // the version for this particular resource
  }
}

Stored resources share some common keys. The first 10 keys in the following example will be the same for any kind of mockup or symbol resource.

{
  "typeID": "DataGrid", // the type of element this is (ie. DataGrid, or TabBar)
  "ID": "2",            // a unique integer for this resource
  "h": "319",           // the pixel height of this resource
  "w": "739",           // the pixel width of this resource
  "x": "30",            // the x position of this resource
  "y": "257",           // the y position of this resource
  "zOrder": "17",       // the position of this resource, front to back
  "properties": {       // resource type specific properties
    "hLines": "false",
    "selectedIndex": "0",
    "size": "14",
    "text": "[CSV formatted data for this DataGrid]",
    "vLines": "true",
    "verticalScrollbar": "true"
  }
}

Each different kind of resource will have properties that are specific to that kind of resource. Note how the highlighted keys within properties differ between the example above and below:

{
  "typeID": "TabBar",
  "ID": "7",
  "h": "535",
  "w": "769",
  "x": "15",
  "y": "52",
  "measuredH": "100",
  "measuredW": "241",
  "zOrder": "2",
  "properties": {
    "borderStyle": "square",
    "color": "15658734",
    "selectedIndex": "0",
    "tabHPosition": "center",
    "text": "[Comma separated list of tab names]"
  }
}

Each Symbol Library that's been added to a project has its own RESOURCE record with JSON data describing all of the controls that that library makes available. Each instance of a control used in a wireframe is described in the JSON within the DATA column for a wireframe's RESOURCE record.

Documenting each different kind of resources, each with their own set of properties, is well beyond the scope of this reference. Knowing the purpose of their common keys should at least provide a foundation for understanding each different kind.


The BRANCHES Table

The branches table contains records for each branch in a project. A typical project will contain a “Master” branch at the very least.

Table Fields
Field Datatype Description
ID TEXT A unique id for a branch
ATTRIBUTES TEXT JSON data. Keys depend on whether the record is for a Master branch or alternate branch.

Master branch example:

{
  "branchDescription":"",       // this is here for possible future use
  "creationDate":1467124505618, // the date this branch was created
  "fontFace":"Chalkboard",      // the name of the font that will be used throughout the project
  "fontSize":16,                // the size of the font that will be used throughout the project
  "linkColor":545684,           // the color used for links throughout the project
  "modifiedBy":[],              // what populates this?
  "projectDescription":"",      // the description for the project
  "selectionColor":9813234,     // the color used for selections throughout the project
  "skinName":"sketch",          // the name of the skin to use throughout the project
  "symbolLibraryID":""          // a unique id for the symbol library used throughout the project
}

An alternate branch example:

{
  "branchName":"alt" // the name of an alternate branch
}

Things to know about branches and alternates:

Balsamiq doesn’t use terms like “branchName” - it uses alternate versions. You can read more about alternate versions here.

This is the “master” alternate. Its ID in the BRANCHES table is “master”, but it has no “branchName” key or value in the ATTRIBUTES column. That’s because the master branch name can’t be changed. Balsamiq will always refer to it as “Official Version”.
This an alternate of the official version. Its ID is an automatically generated UUID and its “branchName” in the ATTRIBUTES column is “Unofficial Version” - its name is editable since it’s not the master branch.
This is another alternate. Its ID is an automatically generated UUID and its “branchName” in the ATTRIBUTES column is “Work in Progress Version”.

Changes made to things like fonts, link colors, project descriptions on an alternative branch are actually made to the Master branch. Alternative branches inherit these properties from the Master branch, which is why alternative branches only contain a branchName.

In this screenshot of Balsamiq we’re picking a new font and changing the link colors to red on one alternate.
Those font changes apply to both the original alternate as well as all other alternates.

Here what the data looks like when the font is changed for an alternate:

That font setting is applied to the master branch, as seen here:


The THUMBNAILS Table

Every Balsamiq project has thumbnails of the wireframes within the project. The THUMBNAILS table keeps track of those thumbnails.

Table Fields
Field Datatype Description Example
ID TEXT

A unique id for a thumbnail.

4B16F0EB-CAD0-5E34-0BD3-DAEDBAF4CAF6
ATTRIBUTES TEXT

JSON data with keys for image, resourceID, and branchID

 

Example:

{
  "branchID":"Master",    // this is the name of the branch this thumbnail is associated with
  "image":"[Image Data]", // contains Base64 encoded data for the thumbnail image.
  "resourceID":"[UUID]"   // this is the UUID of the wireframe this thumbnail is a snapshot of
}

Summary

We hope this reference is useful. If you can think of ways that would help us make it more useful for you we want to hear about it and make it better. If you build a tool that supports BMPR let us know so we can tell people about it!



Edit this page