The BMPR file format

People often ask us if Balsamiq can export to HTML/CSS/JS or XAML or Ruby or other programming languages. In short, we don't, and don't plan to. We don't have the resources to do it, and want to keep our focus on our core product.

Instead, we chose to document our file format, so that developers can build their own tool to integrate with our products, if they wish.

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!

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, thumbnails, and comments. 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 everything there is to know about a Balsamiq project.

Getting a BMPR file

If you want to test out 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.

Versions

The current version of the BMPR file format is 2.0.

We use Semantic Versioning (SemVer for short) for the BMPR file format. This means, among other things, that the API for version 2.x 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 3.0 release will be incompatible with previous major versions.

Balsamiq Mockups 3, released in March 2015, creates BMPR files with 1.2 format. It can open 2.0 files, but new features like Comments are not available.

Balsamiq Wireframes, released in September 2017, creates BMPR file with 2.0 format. It can open 1.2 files, converting them to the new 2.0 format.

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 (2.0) 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 6 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
• USERS informations about people who added comments
• COMMENTS contains all the comments

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.

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.

{
    "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
  }

{
    "mockup": {
      "controls": {        // an array containing each element (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 some 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.

{
    "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 style to use throughout the project
    "symbolLibraryID":""          // a unique id for the symbol library used throughout the project
    }

{
    "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.

{
    "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
    }

The USERS table

Added in version 2.0, the USERS table includes information of anyone who interacted with the Comments feature.

{
    "userName":"cloudUserId-8416193",    // UserID (provided by Balsamiq Cloud in this case)
    "displayName":"John Fritz", // the user name visible to other users
    "email":"johnf@email.com",   // the user email linked to this userID
    "anonymous":false,   // false when the user is registered, true when not
    "inProject":true    // true when the user belongs to the project (it depends on the platform)
    }

The COMMENTS table

Added in version 2.0, the COMMENTS table tracks comments information, such as its text and callouts, threading information, likes and reads.

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!

• ← Keyboard shortcuts
• Autosaving →