The .hoop project file format

.hoop is an open container format for machine-embroidery projects — not just a stitch-out. One file holds the editable design objects, the thread colors, the trace images they were drawn over, and, optionally, a derived stitch list in a machine-neutral form.

This site is the normative reference for format version 1. Anyone may implement readers and writers; no licence, registration or royalty applies to the format itself.

Why a project format

The established machine formats (DST, EXP, PES, JEF) describe a needle path. That is all a machine needs and all they were ever meant to carry. What they cannot carry is the design: the shape a fill was generated from, the width a satin column was given, which thread from which catalogue was intended, or the photo someone traced. Reopening a DST gives you stitches, and a stitch soup cannot be re-digitised — only re-drawn.

.hoop keeps both layers in one file and keeps them honestly separated:

Layer	Entry	Role
Editable project	document.json	The single source of truth
Derived stitches	plan.json	Regenerable output, never imported back

A reader that only wants stitches never has to understand the editable model. A reader that wants to edit never has to trust the stitch list.

The minimum useful reader

Third-party tools that only need to produce machine files have a short job, which is deliberate:

1. Open the archive as a ZIP.
2. Read plan.json.
3. Encode DST, PES, EXP, JEF or anything else from its stitch list.

Coordinates are millimetres, the origin is the hoop centre, y points up. Thread colours carry real catalogue identities rather than a palette index guess. preview.png gives you something to show without rendering anything yourself.

That is the whole contract. The editable model in document.json exists for tools that want to go further, and can be ignored entirely.

Reading order

• Container — what kind of ZIP, which entries, in what order
• manifest.json — versions, checksums, entry roles, recovery
• plan.json — the machine-neutral stitch list; start here for exporters
• document.json — the editable project model
• Reader requirements — compatibility rules and the security limits every reader must enforce
• Versioning — what may change without breaking you

Two real files, Cherry.hoop and Japan.hoop, are available to test against, and the whole specification is also a single PDF.

Conventions in this document

The key words MUST, MUST NOT, SHOULD and MAY carry their usual normative meaning. Requirements marked MUST are what makes an implementation conforming; SHOULD marks a strong recommendation with a legitimate reason to deviate.

Where this site and the reference implementation disagree, the reference implementation is the bug — report it, and this text is what gets fixed.