Skip to content

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.

{
"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 }
]
FieldMeaning
dateWhen the files were made (ISO 8601).
formatThe machine format as the writer names it: dst, exp, expBernina, pes, jef, vp3, tap, hus, xxx. An open set.
appVersionThe application build that wrote the files.
destinationfiles (share sheet, Files, a USB stick) or stick (sent over Bluetooth). An open set.
stitchCount, colorChangesThe encoded plan’s needle-downs and colour changes.
hoopingsHow many hoopings the export was split into; 1 for one hoop.
hoopWidthMM, hoopHeightMMThe 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.

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.

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.

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.

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.

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, … }
}
FieldMeaning
idStable identity. Matches objectID in the plan’s objectRanges.
kindrun, satin, fill or manualStitch.
nameUser-facing label.
isVisibleHidden objects are not stitched.
isLockedEditing guard. Has no effect on output.
colorIndexIndex into palette.
displayOpacityCanvas display only. The stitch file always sews solid thread.
geometryOne of four cases, below.
paramsGenerator parameters for this object’s kind.

Optional per-object fields (absent means the default):

FieldValuesMeaning
groupIDuuidMembership in a groups entry.
postCommandnone | stop | colorChangeA manual machine command after this object. stop pauses without a thread change (trapunto, appliqué); colorChange forces a stop even for the same thread.
trimAfterauto | always | neverThread handling toward the next object. never connects with an uncut jump regardless of distance.
directionLockedbooleanThe 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.)
curveBézier pathThe source the geometry was flattened from, so an editor can keep editing the curve rather than the polyline.
curveWidthProfile, anchorWidthsMM, anchorRungAnglesarraysSatin width and rung angle per curve anchor.
entryAnchor, exitAnchorseam anchorsPinned points where the object is entered and left.
letterIndexintegerWhich letter of a lettering group the object belongs to.
sashikoHostIDuuidThe fill a Sashiko pattern object is drawn on.
smoothMMnumberSmoothing applied to the drawn path.
bastingbooleanSewn as a removable basting line.

Exactly one of four cases, encoded as a single-key object:

CasePayloadUsed 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.

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).

FieldTypeDefaultApplies toMeaning
stitchLengthMMnumber2.2run, fillLength of one stitch along a run, a fill row, or a travel.
passesinteger1run1 single, 3 bean/triple, 5 heavy.
densityMMnumber0.4satin, fillSatin: spacing between penetrations along the column. Fill: spacing between rows. Smaller is denser.
autoSpacingbooleantruesatinLocal column width scales the spacing; densityMM is the baseline at 3 mm width.
angleDegnumber45fillScanline angle; 0 is horizontal rows. Ignored by ring fills and guided fills.
fillPatternenumdiagonalfilldiagonal, 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).
pullCompMMnumber0.2satin, fillOutward widening per side against thread pull.
satinWidthMMnumber3.0satinColumn width for satins drawn as a stroke; the stored rails derive from it.
capStart, capEndenumflatsatinflat, round or point. Open columns only.
tieIn, tieOffenumstandardallnone, small or standard.
underlayobjectsee belowsatin, fillFoundation under the cover.
satinEdgeobjectdisabledfillAutomatic satin border around a fill.
foamobjectdisabledsatin3D puff foam under the column.
sashikoobjectsee belowfillRead only when fillPattern is sashiko.
accordionobjectdisabledsatinSpacing that travels along the column, so the fabric shows through at one end.
fillGuidesarray of point arrays[]fillFlow lines for guided fills: one line means rows run parallel to it, two or more make the angle interpolate between them.
fillGuidepoint arrayabsentfillLegacy. 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.
shadingobjectabsentfillGradient shading of a blend member. Omit unless you are building blend groups.
fillZonesarray of objects[]fillThe region cut into pieces with their own angles: { outer, holes, angleDeg } each. Only the cover pass reads them; empty means one zone at angleDeg.
satinAreaEndsarray of two seam anchorsabsentfillFor fillPattern: "satinArea": where the two ends of the area sit; absent means the ends come from the outline’s curvature.

underlay:

FieldTypeDefaultMeaning
enabledbooleantrueUnderlay on or off.
firmnessenumautoauto, light, standard, firm or custom. Everything except custom overrides types; custom uses types verbatim.
typesarray of enum["centerRun","zigzag"]edgeRun (inset contour run), centerRun (down a satin spine), zigzag (coarse, under satin), tatamiLight (coarse cross-hatch, under fill).
insetMMnumber0.4Inward inset so the underlay never peeks out.
densityMMnumber2.0Spacing of underlay penetrations.
doubleCrossbooleanfalseFill 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.

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.