The Asunder Knit .knit File Format

Last updated: August 19, 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 — 1, 2, or 3 — 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 — the current format for flat knitting. A jagged rows array (described below).
• Version 3 — identical in shape to version 2, but for knitting in the round. The version exists to carry knittingMode: "round" and an optional topClosure, so that a build predating round mode rejects the file with an explicit error rather than misreading it as flat.

The serializer writes version 2 for flat charts and version 3 for round charts. Any other version value is rejected on load.

3. Document shape

A flat (version 2) document has these top-level keys:

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

A round (version 3) document is the same, with knittingMode: "round" and an optional topClosure:

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

• version — 2 (flat) or 3 (round).
• meta — title and timestamps; see section 4. Not read back on load.
• castOnWidth — the cast-on stitch count. See section 9.
• knittingMode — "flat-rs-start", "flat-ws-start", or "round".
• topClosure — version 3 only: "bind-off" or "cinch" (a drawstring / magic-circle crown). Absent means bind-off.
• gauge — stitches and rows per unit, and the unit.
• rows — the stitch grid.
• yarns — the yarn palette.
• repeatGroups — repeat regions.

4. meta

meta is { title, createdAt, updatedAt }. The current release writes title as the constant "Untitled" and sets both timestamps to the time of export on every save. The loader does not read meta back, so these values carry no state between sessions; they are informational only.

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; the stitch definition itself is not embedded. Ids 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).

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

There are no binary payloads, no thumbnails, and no embedded images. 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 .knit document.

Two fields exist in the format schema but are not written by the current release, so they appear only in older or externally authored files: thumbnail (declared but never written or read) and customStitches (read on load and merged into the stitch library, but never written, so a save round-trip discards them).

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, 2, or 3 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. 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 writes version 2 for flat charts and version 3 for round charts.
• Version 1 files still load but are never written.
• The format contract is the JSON contents, not the filename suffix.

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