Krazy Stitcher Open Pattern Format

Start here

A small example

A 3 by 2 loom pattern: a red and a black bead on the top row, then a red bead, an empty space and a black bead.

{
  "ksFormat": 1,
  "name": "Tiny sample",
  "type": "loom",
  "width": 3,
  "height": 2,
  "grid": ["#AE050C", "#111111", null,
             "#AE050C", null, "#111111"],
  "colorMap": {
    "#AE050C": { "id": "DB0723", "name": "Opaque Red" },
    "#111111": { "id": "DB0010", "name": "Black" }
  },
  "notes": "Start at the top left."
}

The colors and codes are Miyuki Delica DB0723 and DB0010 as Krazy Stitcher lists them. Krazy Stitcher writes more fields than this (for example id, created, modified, shape and fringe); a reader may ignore any field it does not need.

May be left out

Optional fields

All of these may be left out. “Edition” says which editions have a tool for the field; every edition keeps every field when it opens and saves a pattern.

Studio’s Pattern Package cover design and its “Buy” links are not part of the pattern: they are remembered in the browser, so they are not in the file.

The colorMap field

Beads and brands

Each colorMap entry may have id (the bead code, for example DB0010 for Miyuki Delica Black), name, finish (the finish chosen while drawing, for example matte; missing = standard) and brand. Other text, number and true/false fields are kept. The pattern does not store a palette: the bead code and name say which bead it is.

brand is written by Brand Swap and is one of delica, toho, preciosa, rocailles, matsuno, millhill. Colorways use their own brand ids: miyuki, toho, preciosa, miyukiRocailles, matsuno, millHill. The two lists are spelled differently; this page records them as the app writes them.

Opening untrusted files

What is checked when a file is opened

Pattern files are treated as untrusted. A file is not opened when it is not a JSON object, has no valid width, height or grid, is larger than the limits above, has a grid of the wrong length, uses an unknown stitch type, nests more than 64 levels deep, or has a ksFormat that is not a whole number from 1 to 1,000. A pattern that is already yours (kept in the browser, in a backup, in the pattern folder or in version history) is never dropped for a bad ksFormat: the bad value is removed and the pattern stays.

Anything else that is wrong is cleaned and the file opens: a cell that is not #rrggbb becomes empty, a color entry with a bad key is removed, a layer with a grid of the wrong length is removed, long names and notes are shortened, control characters are removed from text, and numbers are kept within their range. The message after opening says how many cells, colors, layers, names and notes were changed. The keys __proto__, constructor and prototype are removed everywhere.

Fields this version does not know are kept when the name is at most 60 characters and does not start with _. Their values are kept as plain JSON: text up to 2,000 characters, lists up to 1,000 items, objects up to 200 keys, three levels deep. Names that start with _ are the app’s own temporary data; they are never written and are dropped when read.

.ks, .json, .ksp

Files that use this layout

• .ks: one pattern, compact JSON (Export Pattern / Save File, and the pattern folder).
• .json: one pattern, indented JSON (Export Open Format, Pro and Studio).
• .ksp: a zip package with the .ks file plus a PNG, a PDF chart, a word chart, a bead count CSV and metadata.json. With a password, the pattern is in .ks.enc instead and is encrypted.
• .ksbackup (Backup All) is a different file: it holds many patterns plus palettes and inventory. Each pattern inside follows this layout, without ksFormat.

Files are UTF-8 text. The pattern folder does not open files over 50 MB.