document.json
document.json is the editable project and the single source of truth.
Everything else in the archive is either derived from it or metadata about it.
This page describes the structure a reader can rely on, and — since writers
need names, not prose — the stitch parameters as they stand today. That
table is a snapshot: the parameter set grows additively with the
application, so treat it as enough to get started, never as a closed list.
For the exhaustive, authoritative definitions, read the Codable types in the
reference implementation under Packages/Core/Sources/DocumentKit/.
If you only need stitches, you do not need this page at all — see plan.json.
Top level
Section titled “Top level”{ "formatVersion": 1, "id": "<uuid>", "meta": { "title": "Cherry", "createdAt": …, "modifiedAt": …, "appVersion": "0.1", "author": "Mika", "notes": "Jersey, two layers of stabiliser" }, "hoop": { "name": "130 × 180 mm", "widthMM": 130, "heightMM": 180 }, "palette": [ { "red": 47, "green": 48, "blue": 50, "catalogId": "madeira-polyneon", "code": "1800", "name": "Black" } ], "projectColors": [ … ], "groups": [ { "id": "<uuid>", "name": "Cherry 1 blend", "joined": false } ], "references": [ … ], "objects": [ … ], "settings": { "maxTravelMM": 6, "fabric": "knit", … }}All coordinates are millimetres, hoop-centred, y up — the same system as plan.json.
title, createdAt, modifiedAt and appVersion, plus — since 2026-09-26 —
the optional author and notes: free text that travels with the file and is
printed on the application’s worksheet. Absent means none; a writer that has
nothing to say leaves both out rather than writing empty strings.
Since 2026-11-08 meta may also carry exports: what the design remembers
of its machine-file exports, newest last, at most 20 entries. A file sent in
for support then says how its machine files were made — which format, which
app build, whether they went to a file or to a stick — without anyone having
to ask.
"exports": [ { "date": "2026-11-08T17:18:43Z", "format": "vp3", "appVersion": "1.0.2 (10)", "destination": "files", "stitchCount": 3487, "colorChanges": 5, "hoopings": 1, "hoopWidthMM": 160, "hoopHeightMM": 260 }]| Field | Meaning |
|---|---|
date | When the files were made (ISO 8601). |
format | The machine format as the writer names it: dst, exp, expBernina, pes, jef, vp3, tap, hus, xxx. An open set. |
appVersion | The application build that wrote the files. |
destination | files (share sheet, Files, a USB stick) or stick (sent over Bluetooth). An open set. |
stitchCount, colorChanges | The encoded plan’s needle-downs and colour changes. |
hoopings | How many hoopings the export was split into; 1 for one hoop. |
hoopWidthMM, hoopHeightMM | The hoop the files were made for. |
Absent means no export is remembered. The list is a memory, not the design: a reader clamps each field (texts to 64 characters without control characters, counts to 0…10⁸, lengths to 0…10 000 mm) and drops a list it cannot read — never the design. A writer keeps the newest 20 entries.
palette
Section titled “palette”Ordered thread colours. Objects reference them by index, which makes the array structural: an entry an object refers to MUST NOT be removed, and reordering it changes the design. Fields are the same as in the plan’s colorTable.
projectColors is a separate, non-structural convenience list — the user’s
quick-access swatches. Nothing references it by index; a reader may ignore it.
groups
Section titled “groups”Named groupings of consecutive objects. joined: true marks a group whose
members were welded into one continuous stitch path rather than merely grouped.
Membership is expressed on the objects, not here.
A group may carry one section recipe, each key optional and absent by
default: lettering (live text), puff (3D foam), trapunto (wadding
outline: marks, markLegMM, markMarginMM, stops; since 2026-09-11 also
shapeStitchLengthMM and shapePasses for the shaping pass — absent means as
the outline — and shapeInsetMM, default 0: the shaping pass sews that far
inside the drawn line, which is the seam on the fabric; closed outlines only.
Readers accept outlineOffsetMM as the same value from files written on
2026-09-11), applique (placement, tack-down, cover ring; files written on
2026-09-11 may carry cutOffsetMM / cutMirrored, which readers ignore — the
plotter’s choices moved to the export) and border ({ sourceGroupID, kind, placement, presetID } — an outline that follows another group). A reader that
does not know a recipe keeps the group and its members as plain objects; the
recipe’s generated steps are derived, never stored.
references
Section titled “references”Trace images the design was drawn over: { id, name, centerMM, widthMM, rotationDeg, opacity, isVisible, isAboveStitches }. isAboveStitches (added
2026-09-06, default false) draws the image over the stitches instead of under
them — display only, never exported. This is metadata only — the image bytes live in the archive
under references/<uuid>.<ext>, matched by the lowercased UUID prefix of the
entry name. See Container.
settings
Section titled “settings”Project-wide values, for example maxTravelMM (the distance beyond which a
connection becomes a trim rather than a stitched travel), the target fabric,
and the display unit. Additive: expect keys you do not know.
objects
Section titled “objects”The design itself. Array order is stitch sequence — the first object is sewn first, and that is also the drawing order, so later objects sit on top of earlier ones.
{ "id": "<uuid>", "kind": "fill", "name": "Fill 1", "isVisible": true, "isLocked": false, "colorIndex": 0, "displayOpacity": 1.0, "geometry": { "region": { "outer": [ … ], "holes": [ … ] } }, "params": { "densityMM": 0.35, "stitchLengthMM": 2.5, "angleDeg": 45, … }}| Field | Meaning |
|---|---|
id | Stable identity. Matches objectID in the plan’s objectRanges. |
kind | run, satin, fill or manualStitch. |
name | User-facing label. |
isVisible | Hidden objects are not stitched. |
isLocked | Editing guard. Has no effect on output. |
colorIndex | Index into palette. |
displayOpacity | Canvas display only. The stitch file always sews solid thread. |
geometry | One of four cases, below. |
params | Generator parameters for this object’s kind. |
Optional per-object fields (absent means the default):
| Field | Values | Meaning |
|---|---|---|
groupID | uuid | Membership in a groups entry. |
postCommand | none | stop | colorChange | A manual machine command after this object. stop pauses without a thread change (trapunto, appliqué); colorChange forces a stop even for the same thread. |
trimAfter | auto | always | never | Thread handling toward the next object. never connects with an uncut jump regardless of distance. |
directionLocked | boolean | The path direction is authored — lettering chains, where each stroke begins where the previous one ended — and a generator MUST NOT flip it to save travel. (Corrected 2026-09-10; an earlier revision described it as a shared stitch angle.) |
curve | Bézier path | The source the geometry was flattened from, so an editor can keep editing the curve rather than the polyline. |
curveWidthProfile, anchorWidthsMM, anchorRungAngles | arrays | Satin width and rung angle per curve anchor. |
entryAnchor, exitAnchor | seam anchors | Pinned points where the object is entered and left. |
letterIndex | integer | Which letter of a lettering group the object belongs to. |
sashikoHostID | uuid | The fill a Sashiko pattern object is drawn on. |
smoothMM | number | Smoothing applied to the drawn path. |
basting | boolean | Sewn as a removable basting line. |
geometry
Section titled “geometry”Exactly one of four cases, encoded as a single-key object:
| Case | Payload | Used by |
|---|---|---|
centerline | { "points": [ … ] } | Runs, and satins defined by a centre line plus a width |
rails | { "railA": [ … ], "railB": [ … ] } | Satins digitised as two rails |
region | { "outer": [ … ], "holes": [[ … ], … ] } | Fills, with optional holes |
points | { "points": [ … ] } | Manual stitches |
Points are { "x": Double, "y": Double } in millimetres. Rails in the rails
case are index-paired: railA[i] faces railB[i], and the pairing is what
defines each stitch, not arc length. A reader that re-samples one rail without
the other destroys the column.
params
Section titled “params”Generator parameters. Which keys are meaningful depends on kind — a fill
ignores satinWidthMM, a run ignores angleDeg.
Every field is optional on read: a reader substitutes the default for
anything absent, so a writer only sets what its object kind actually uses.
The table below is what a writer needs to produce a design today. It is a
snapshot, not a closed list — the set grows, new keys appear in minor
revisions without a formatVersion bump, and a reader MUST ignore the
ones it does not know (compatibility rules).
| Field | Type | Default | Applies to | Meaning |
|---|---|---|---|---|
stitchLengthMM | number | 2.2 | run, fill | Length of one stitch along a run, a fill row, or a travel. |
passes | integer | 1 | run | 1 single, 3 bean/triple, 5 heavy. |
densityMM | number | 0.4 | satin, fill | Satin: spacing between penetrations along the column. Fill: spacing between rows. Smaller is denser. |
autoSpacing | boolean | true | satin | Local column width scales the spacing; densityMM is the baseline at 3 mm width. |
angleDeg | number | 45 | fill | Scanline angle; 0 is horizontal rows. Ignored by ring fills and guided fills. |
fillPattern | enum | diagonal | fill | diagonal, brick, scatter, wave, chevron, contour (shown as Ring in the app since 0.9.1 — the raw value stays for compatibility), guided, sashiko, satinArea (the region sewn as one satin, rail to rail). |
pullCompMM | number | 0.2 | satin, fill | Outward widening per side against thread pull. |
satinWidthMM | number | 3.0 | satin | Column width for satins drawn as a stroke; the stored rails derive from it. |
capStart, capEnd | enum | flat | satin | flat, round or point. Open columns only. |
tieIn, tieOff | enum | standard | all | none, small or standard. |
underlay | object | see below | satin, fill | Foundation under the cover. |
satinEdge | object | disabled | fill | Automatic satin border around a fill. |
foam | object | disabled | satin | 3D puff foam under the column. |
sashiko | object | see below | fill | Read only when fillPattern is sashiko. |
accordion | object | disabled | satin | Spacing that travels along the column, so the fabric shows through at one end. |
fillGuides | array of point arrays | [] | fill | Flow lines for guided fills: one line means rows run parallel to it, two or more make the angle interpolate between them. |
fillGuide | point array | absent | fill | Legacy. A single flow line, written by versions before fillGuides existed. Readers should treat a present fillGuide as the first entry of fillGuides; writers should not emit it. |
shading | object | absent | fill | Gradient shading of a blend member. Omit unless you are building blend groups. |
fillZones | array of objects | [] | fill | The region cut into pieces with their own angles: { outer, holes, angleDeg } each. Only the cover pass reads them; empty means one zone at angleDeg. |
satinAreaEnds | array of two seam anchors | absent | fill | For fillPattern: "satinArea": where the two ends of the area sit; absent means the ends come from the outline’s curvature. |
underlay:
| Field | Type | Default | Meaning |
|---|---|---|---|
enabled | boolean | true | Underlay on or off. |
firmness | enum | auto | auto, light, standard, firm or custom. Everything except custom overrides types; custom uses types verbatim. |
types | array of enum | ["centerRun","zigzag"] | edgeRun (inset contour run), centerRun (down a satin spine), zigzag (coarse, under satin), tatamiLight (coarse cross-hatch, under fill). |
insetMM | number | 0.4 | Inward inset so the underlay never peeks out. |
densityMM | number | 2.0 | Spacing of underlay penetrations. |
doubleCross | boolean | false | Fill only: two diagonal passes instead of one. |
satinEdge: enabled (boolean, false), widthMM (number, 1.0),
insetMM (number, 0).
foam: enabled (boolean, false), densityMM (number, 0.3),
tearInsetMM (number, 0.5), endCaps (boolean, true — a satin bar across
each open column end).
sashiko: motif (grid, asanoha, seigaiha, kikko, igeta, shippo,
amime, tatewaku, uroko, yabane or sayagata),
scaleMM (number, 8), stitchLengthMM (number, 2.5), angleDeg
(number, 0), insetMM (number, 0.5), passes (integer, 1).
accordion: profile (off, fadeOut, fadeIn, bothEnds or
feather), openMM (number, 1.4 — the spacing reached at the open end,
against densityMM at the dense end), and the optional pair axisStart /
axisEnd (points). Without the axis each column fades over its own
length; with it, every column measures its position along that one line,
which is how a word fades across its letters rather than each letter
fading by itself. profile: off means the whole object is unaffected —
that is the value in almost every file.
These are design values. A generator may compensate them when it
derives stitches — StitchPencil tightens density, underlay and pull
compensation for knit and pile fabrics (settings.fabric) — without ever
writing the compensated numbers back into the object.
What a reader should not conclude
Section titled “What a reader should not conclude”document.json describes intent, not output. The number of stitches an object
produces, where its seam lands, whether a connection becomes a trim — all of
that is the result of running a generator over these parameters, and it is not
recorded here. If you need the stitches, read the plan; if you need to
regenerate them yourself, you are re-implementing the generators, and this file
is the input, not the answer.