Sketch 43 will introduce a new file format, designed to allow better integration with third party services and external tools. It will allow developers to access document information in an easier way, without having to use SketchTool. This opens new possibilities for inspecting Sketch documents in non-macOS platforms.

In case you're wondering: SketchTool is not going anywhere. We're committed to it, and have some new features in the pipeline. Also, you'll still need it if you want to extract assets from a Sketch document.

In this post we’ll explain how this new file format is structured, and some of the things you can do with it…

A zipped folder 📦

New Sketch documents are basically zipped folders, containing JSON files that describe the document data, plus a number of binary assets (bitmap images, document preview…)

We'll take a look at a sample document, Fitness App. This is a Sketch 43 document, so don’t try to open it with a prior version of Sketch. We just released a public beta for v43 in case you want to play with it.

To explore its contents, we'll rename it to Fitness App.zip and double click it to expand it. We'll see it contains a folder structure similar to this:

- images - 0c2421c7228cf5e9d8133b6f598461a7cf439fc5.png - 00f051d3a27fec14ba725121eb2bffb3ac1c3e02.png - etc… - pages - 9B2D6A75-D2C0-40F3-88AB-AE4BD625E520.json - 866BD861-A247-4826-A32A-C8DE4F109578.json - previews - preview.png - document.json - meta.json - user.json

Let’s take a look at those files and folders:

meta.json

Contains metadata about the document itself (a list of pages and artboards, Sketch version used to save the file, fonts used…). It's equivalent to the output you'd get from running sketchtool metadata on the file.

document.json

Contains common data for all pages of a document, like shared styles, and a link to the JSON files in the pages folder.

pages folder

Contains a JSON file per page of the document. Each file describes the contents of a page, in a format similar to what you'd get by running sketchtool dump on the file.

images folder

The images folder contains all the bitmaps that are used in the document, at their original scales (so if the user imported a 1000x1000px image and then resized it to 200x200px, the full 1000x1000px file will be stored).

user.json

Contains user metadata for the file, like the canvas viewport & zoom level for each page, UI metadata for the app (panel dimensions, etc…) and whether the document has been uploaded to Sketch Cloud.

previews folder

Contains a preview image of the last page edited by the user. If the page's size is less than 2048x2048 it will be stored at full size, otherwise it'll be scaled to fit a 2048x2048 square.

A file format for hackers 🛠

You can do some funky stuff with the contents of a Sketch document, once you expand the ZIP.

If you edit any asset or JSON, and then put them back into the ZIP file, Sketch will read those changes back.

Keep in mind though, that the new file format its great for reading stuff back out. Making changes is less trivial as there may be unexpected properties hanging together, like a text layer’s frame and its string contents causing unexpected wrapping…

Here are some ideas for things you can try to do with the documents:

editing page and layer names by editing the JSON

running bitmaps through ImageOptim to compress them

run text diffs using version control systems

run visual diffs using previews + version control systems

integrating previews for .sketch documents on your server-side apps

use server-side tools to generate a dynamic .sketch document

…

With great power comes great responsibility 💣

Please note that for efficiency, we’re doing minimal error-correction when reading the document back, so if you make an incompatible change it’s quite possible to end up with an invalid document. Always work on backups, and treat your user’s documents with care.

Also, since the JSON files are machine-generated, the structure will definitely change in the future as we keep evolving the file format. We will migrate older structures, of course, but keep it in mind when developing your integrations.

Hello, future 👋

We look forward to seeing what you can do with this new file format, and can’t wait to hear your feedback. If there’s anything you’re missing, something you’d like us to implement, or you need help with some incredible integration that will awe the world, send us a note to <developers@sketchapp.com> and we’ll be happy to chat with you.

Have a nice day!