Skip to content

Versioning

manifest.json → formatVersion is the only version a reader has to branch on. It increases only when a conforming reader of the previous version would get the file wrong.

  • New keys in any JSON object.
  • New entries in the archive.
  • New values in an open set — thread catalogue identifiers, entry roles, parameter sub-objects.
  • New optional per-object fields whose absence has a defined default.

All of these are safe precisely because of the first compatibility rule: readers ignore what they do not recognise. A reader written against version 1 today will still open version 1 files written years from now, with the features it knows about intact and the rest ignored.

  • Removing or renaming an existing key.
  • Changing the meaning, unit or coordinate system of an existing value.
  • Changing the container in a way an existing reader cannot parse.

There is no minor version number. A file either declares a formatVersion you support, or it does not.

Version 1 has already grown this way. The document model gained groups, a directionLocked flag per object, and a series of parameter sub-objects for features that did not exist when the format was published. The manifest gained the gallery summary fields. None of it moved the version, and a reader from the first day still opens today’s files.

That is the intended behaviour, not a loophole — and it is why these pages describe the shape of document.json → params rather than enumerating it.

formatVersionDateChanges
12026-07-11Initial public specification.
1 (additive)2026-09-10Reader rule 5 (lenient enums); group section recipes and the optional per-object keys; satinArea, fillZones, satinAreaEnds, more Sashiko motifs, foam.endCaps; directionLocked corrected.
1 (additive)2026-09-11trapunto: shapeStitchLengthMM, shapePasses, shapeInsetMM (briefly outlineOffsetMM). applique: cutOffsetMM, cutMirrored — withdrawn the same day, ignored by readers.
1 (additive)2026-09-26Manifest author; meta.author, meta.notes; references[].rotationDeg, isVisible, isAboveStitches (the last since 2026-09-06); Sashiko uroko, yabane, sayagata (2026-09-23).
1 (additive)2026-11-08meta.exports — the design’s machine-file exports (date, format, app build, destination, plan size, hoopings, hoop). Older readers ignore it.

Additive clarifications to version 1 are edited into these pages in place. A breaking change adds a row here and bumps the number in every file written afterwards.

If a .hoop file written by StitchPencil disagrees with anything on this site, the file is right and this text is wrong — the specification documents the format, it does not define it retroactively. Discrepancies are worth reporting; they get fixed here.