The Asunder Knit .knit File Format

Last updated: August 27, 2026

This is a technical reference for the Asunder Knit .knit file format, intended for anyone reading, generating, or reverse-engineering a saved file. It describes what the current release of Asunder Knit writes and reads.

1. Container format

A .knit file is a single plain UTF-8 JSON document. It is not a ZIP archive, it carries no binary payload, and it embeds no assets. The serializer writes it pretty-printed with two-space indentation, and the saved filename takes the form knit_2026-08-19T14-32-05.knit — an ISO 8601 timestamp with colons and periods replaced by hyphens.

The extension is not part of validation. The loader identifies a file by parsing it as JSON and reading the version field; the file picker accepts both .knit and .json, and either extension loads identically.

The top level is a single flat JSON object. There is no plugin-keyed envelope and no per-store token map; one object holds the entire chart.

2. The version field

version is a plain number — currently 1 through 5 — not a semver string.

• Version 1 — legacy. A flat cell array plus an explicit dimensions object. Read-only: the current release loads it but never writes it.
• Version 2 — legacy flat format. Introduced the jagged rows array described below.
• Version 3 — legacy round format. It added knittingMode: "round" and optional topClosure.
• Version 4 — legacy all-mode format. It introduced turn symbols for short rows.
• Version 5 — the current format. It replaces the independent round topClosure setting with the complete roundForm construction.

The serializer always writes version 5. Versions 1–5 all remain readable, and opening then saving an older file upgrades it to version 5. Any other version is rejected. A legacy round topClosure: "cinch" migrates to roundForm: "hat"; an absent or "bind-off" closure migrates to "tube". No legacy file is inferred to be the planar "flat" round form.

3. Document shape

A flat-knitted version 5 document has these top-level keys:

{
  "version": 5,
  "meta": { "title": "Untitled", "createdAt": "...", "updatedAt": "..." },
  "castOnWidth": 24,
  "knittingMode": "flat-rs-start",
  "gauge": { "stitchesPerUnit": 5, "rowsPerUnit": 7, "unit": "inch" },
  "rows": [ [ ... ], [ ... ] ],
  "yarns": [ ... ],
  "repeatGroups": [ ... ]
}

A round version 5 document adds the required roundForm discriminator:

{
  "version": 5,
  "meta": { "title": "Untitled", "createdAt": "...", "updatedAt": "..." },
  "castOnWidth": 60,
  "knittingMode": "round",
  "roundForm": "hat",
  "gauge": { "stitchesPerUnit": 5, "rowsPerUnit": 7, "unit": "inch" },
  "rows": [ ... ],
  "yarns": [ ... ],
  "repeatGroups": [ ... ]
}

• version — 5 for every file written by the current release.
• meta — title and timestamps; see section 4.
• castOnWidth — the cast-on stitch count. See section 9.
• knittingMode — "flat-rs-start", "flat-ws-start", or "round".
• roundForm — required when knittingMode is "round" and forbidden otherwise; "tube", "hat", or "flat".
• gauge — stitches and rows per unit, and the unit.
• rows — the stitch grid.
• yarns — the yarn palette.
• repeatGroups — repeat regions.
• customStitches — optional document-scoped stitch definitions.
• thumbnail — optional preview payload preserved when present.

4. meta

meta is { title, createdAt, updatedAt }. The loader retains the document's title and creation timestamp. Saving preserves those two values and stamps only updatedAt with the current time. A missing title defaults to "Untitled", and a missing creation timestamp defaults to the load time.

5. The stitch grid

rows is a jagged, row-major array of arrays: rows[row][col]. Each row may be a different length. Row 0 is the bottom of the chart — the first row knitted — and rows count upward from there.

The chart's working width is derived from stitch content, not from array length. Trailing empty cells carry no width, so a row's array length is not a reliable measure of its stitch count. The effective cast-on width is derived from the stitches the first worked row consumes; the stored castOnWidth is a creation-time value retained for reference.

6. Cell encoding

Each cell is encoded compactly with up to three optional keys, and takes one of three forms:

• No stitch (empty / erased) — the empty object {}.
• A worked stitch — { "s": stitchId, "y": yarnId }.
• A cable continuation — { "c": [anchorCol, anchorRow] }, pointing back to the anchor cell of a multi-column stitch.

[
  {},
  { "s": "knit", "y": "id_0" },
  { "s": "2/2 RC", "y": "id_1" },
  { "c": [2, 5] }
]

The three keys are: s (stitch id), y (yarn id), and c (the [column, row] anchor coordinate for a continuation). A wide stitch such as a cable occupies one anchor cell carrying s and y, followed by c continuation cells whose coordinates point back to that anchor. If a stitch cell omits y, the loader falls back to the first yarn in the palette.

7. Stitch ids and the library

A cell stores only a stitch id string in s. Ids normally resolve against Asunder Knit's built-in stitch library of 38 stitches — knits and purls, slips, twisted stitches, and a large family of decreases and increases (for example knit, purl, k2tog, ssk, yo, m1l, cdd).

A file may additionally carry customStitches. Those definitions are available only while that document is open and are preserved verbatim when it is saved. A custom definition cannot replace a built-in with the same id; built-in semantics win.

Cables use structured span ids as the s string, in the form "2/2 RC", "1/1 LC", or "2/1 LPC" (columns held front/back, then lean and purl markers). There are 20 preset cable spans, and arbitrary custom spans resolve directly from their id without a library entry.

8. Yarns and the physical yarn model

yarns is the palette. Cells reference a yarn by its id. Each entry is { id, name, color, model }, where color is a 6-digit hex string and is treated as the yarn's unique key — no two palette entries share a color.

{
  "id": "id_0",
  "name": "Worsted Wool",
  "color": "#9d5821",
  "model": {
    "id": "id_0",
    "name": "Worsted Wool",
    "fibers": [ { "fiber": "wool", "percentage": 100 } ],
    "wpiThickness": 9,
    "plyCount": 3,
    "twistDirection": "Z",
    "tpi": 4,
    "convention": "knitting",
    "color": "#9d5821",
    "gristTex": 98,
    "elasticityMPa": 12,
    "frictionMu": 0.3,
    "stiffnessEI": 0.0004,
    "compressibilityKPa": 40,
    "sheen": 0.2
  }
}

model is the full physical yarn model (shared with Asunder's weaving app, Bower). It captures fiber content as a blend that sums to 100%, thickness in wraps-per-inch, ply count and twist (S or Z direction, turns-per-inch), spinning convention, and the physical constants the 3D yarn simulation needs — grist (linear density), elasticity, friction, bending stiffness, compressibility, and sheen. The current release always writes model; it is optional in the schema only so that files predating the physical model still load.

9. Gauge, cast-on, and mode

10. Repeat groups

repeatGroups is an array of repeat regions. Each carries an id, a repeatCount, an optional label, and a rows map from row index to a { startCol, endCol } span.

{
  "id": "id_7",
  "repeatCount": 4,
  "label": "Cable panel",
  "rows": {
    "0": { "startCol": 2, "endCol": 9 },
    "1": { "startCol": 2, "endCol": 9 }
  }
}

11. What is not in the file

The format is one JSON document, not a ZIP or binary container. The 3D yarn simulation's baked geometry is runtime-only and is never serialized. PNG, SVG, and PDF outputs are separate one-way exports, not part of the chart document.

Two optional compatibility payloads may appear: thumbnail and customStitches. The current UI does not create them, but the loader reads them and the serializer writes them back unchanged, so opening and saving a file does not discard schema-supported data.

12. Load validation and recovery

Loading does more than parse JSON. The loader enforces several consistency rules and repairs a few classes of damage rather than failing outright:

• Version gate — only 1 through 4 load; anything else is rejected.
• Mode matches version — a version 1 or 2 file must be flat, and a version 3 file must be round. Version 4 accepts every supported knitting mode. A mismatch is rejected.
• Yarn models are validated — fiber percentages must sum to 100, colors must be hex, twist must be S or Z, and physical constants must be positive.
• Duplicate colors are folded — palette entries sharing a color are merged and the affected cells repointed, upholding the one-color-per-yarn rule.
• Missing yarns are recovered — a cell that names a yarn absent from the palette is repointed onto a single grey "Recovered" yarn instead of crashing.
• Cable anchors are repaired — continuation cells naming a stale anchor row are re-anchored on load.

Loading is transactional: the loader snapshots the current document, attempts the load, and on any error rolls back to the snapshot, so a corrupt file cannot leave a half-loaded chart. The same serialized shape backs the browser autosave, which mirrors the chart to local storage.

13. Compatibility and versioning

• Files use the .knit suffix, and .json is also accepted on load.
• The app always writes version 5, whether the chart is flat-knitted or round.
• Versions 1–4 still load but are never written; saving upgrades them to version 5.
• The format contract is the JSON contents, not the filename suffix.

Open Asunder Knit and save a chart to inspect the format directly →