Serialized Data Format

Ian Prest edited this page Feb 22, 2017 · 22 revisions

This page describes the serialized data format used by

Top-Level Structure:

The serialized data is a JSON array of keyboard "rows", with an optional JSON object describing keyboard metadata.

  { /*keyboard metadata; optional*/ },
  [ /*row 1*/ ],
  [ /*row n*/ ]

Keyboard Metadata:

Optionally, the first entry in the top-level JSON array can be a JSON object describing the keyboard metadata. Supported metadata properties are:

  • "backcolor" (string)
    • the background color for the keyboard editor area (default "#eeeeee")

Keyboard Rows:

Each keyboard row in the serialized data is a JSON array of keycaps, each of which is a string:

[ "Q", "W", "E", "R", "T", "Y" /*etc*/ ], // row 1
[ "A", "S", "D", "F", "G", "H" /*etc*/ ], // row 2
// ...

If a keycap has multiple legends, each legend is separated by a newline character \n. The order of legend positions is as follows:

"top left\n
 bottom left\n
 top right\n
 bottom right\n
 front left\n
 front right\n
 center left\n
 center right\n
 top center\n
 bottom center\n
 front center"

The string of the keycap is cut off at the last non-empty legend. For example, a keycap that is labeled 'Q' at the top left and '1' at the top right is encoded by the string "Q\n\n1".

When processing keys within a row, the current position is updated after each key:

  • The first row starts with coordinate y = 0 by default; each subsequent row increments the y coordinate by 1.0.
  • Each row resets the coordinate x = 0.
  • After each keycap, the current x coordinate is incremented by the previous cap's width.

Keycap properties can be modified by inserting a JSON object into the row before the key(s) to which it applies, e.g.:

  { "c" : "#ff0000" }, // set keycap color to red
  "Q", "W", "E", "R", "T", "Y", "U", "I", "O", "P", "[", "]", 
  { "w" : 1.5 }, // set keycap width to 1.5u

Note that some of the properties apply only to the next keycap, while other properties apply to all subsequent keycaps. The following properties apply only to the next keycap:

  • "x", "y" (number)
    • These specify x and y values to be added to the current coordinates.
    • For example, specifying x = 1 will leave a 1.0x gap between the previous key and the next one.
  • "w", "h" (number)
    • These specify the width and height of the next key.
  • "x2", "y2", "w2", "h2" (number)
    • These specify the offset and size of the second rectangle that is used to define oddly-shaped keys.
  • "l" (number)
    • Specifies that the next key is a "stepped" key (often used for "Caps Lock" keys).
  • "n" (boolean)
    • Specifies that the next key is a "homing" key (which usually renders as a little "nub").

The following properties apply to all subsequent keycaps:

  • "c" (string)
    • Specifies the color of the keycap, in "#rrggbb" format, e.g., "#ff0000" indicates red.
  • "t" (string)
    • Specifies the color of the text on the keycap, in "#rrggbb" format.
  • "g" (boolean)
    • Specifies that the following keys are 'ghosted'
  • "a" (number)
    • Specifies the text alignment. This is a bit field of one or more of the following:
      • 0x01 - Center labels in the X direction
      • 0x02 - Center labels in the Y direction
      • 0x04 - Center the side-printed text
  • "f", "f2" (number)
    • Specifies the primary & secondary font heights, on a scale of 1-9 (default 3)
  • "p" (string)
    • Specifies the profile & row of the keycaps.
    • Supported profiles: DCS, DSA, SA
    • Supported profile "modifiers": SPACE, R1, R2, R3, R4, R5

The following properties are not implemented, but are proposed for future use:

  • "s" (string)
    • Style of the keycap; this is a reference to a keycap prototype.


While the data format is standard JSON, to reduce the visual clutter and make it more readable and easier to edit, the "raw data" tab in the editor relaxes the normal rules by allowing key names to be specified without quotation marks. It also removes the opening and closing square brackets around the entire array.

If you 'upload' or 'download' the layout as a JSON file, it will adhere to the strict JSON grammar.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.