Practical guide
How to open a .wwd file
A .wwd package is an ordinary ZIP archive holding JSON. Nothing proprietary is needed to read one, and two validators exist to check that a package is conformant rather than merely readable.
Six steps
From an unknown file to a checked package.
- 01
Confirm the file is a WWD package
A .wwd file is a ZIP archive whose first entry is named mimetype, is stored uncompressed, and contains exactly the bytes application/vnd.wwd+zip. Running file on the package, or reading that first entry, identifies the format without unpacking anything else.
- 02
List the archive with any unzip tool
Run unzip -l package.wwd. A minimal package has three entries: mimetype, wwd/manifest.json and wwd/design.json. An as-built package adds wwd/results.json, and further entries carry delegated assets such as a mesh, a print job or an assay CSV.
- 03
Read the design document
Run unzip -p package.wwd wwd/design.json. It prints the design as JSON: the root component, the revision, the components with their frames, dimensions, regions, interfaces, biological populations and property fields, and the acceptance criteria. No WWD software is needed to read it.
- 04
Read the manifest and check what else is in the package
Run unzip -p package.wwd wwd/manifest.json. It lists every payload with its logical name, media type, byte length, SHA-256 integrity digest and role, plus the extensions the package uses and the ones it requires. A consumer that does not support a required extension must refuse to process the package.
- 05
Validate the container in your browser
Open the validator on this site and drop the package in. It checks the container layer: that the archive is readable, that the mimetype entry is correct, that there is exactly one manifest and a parseable root design document, that every declared file is present at its declared length with a matching digest, and that no required extension is unsupported. The file is read locally and is never uploaded.
- 06
Validate semantics and design rules with the reference validator
The reference implementation is Python 3.11 or later, standard library only at runtime. Run python -m wwd package.wwd to validate, --schema to cross-check against the JSON Schemas, --dfm to run the design rules, --conformance to see which conformance classes the package reaches, and --causal to print the interventional projection of an as-built package.
Inspecting the archive
The commands, on a package downloaded from this site.
The first entry is mimetype, stored uncompressed, containing exactly
application/vnd.wwd+zip with no trailing newline. This is the rule ODF
and EPUB use, and it is why the format can be identified from the first bytes of the
file without inflating anything.
Everything else is manifested. If a file appears in the archive that the manifest does not list, that is a finding rather than a convenience: an undeclared file carries no integrity guarantee and a consumer may only look at it during forensic recovery.
unzip -l muscle-strip-designed.wwd
unzip -p muscle-strip-designed.wwd mimetype
unzip -p muscle-strip-designed.wwd wwd/manifest.json
unzip -p muscle-strip-designed.wwd wwd/design.json
unzip -p muscle-strip-asbuilt.wwd wwd/results.jsonEvery example package on this site is a real archive, not an illustration. Download the as-designed muscle strip and run these against it.
Validating a package
Two validators, at different depths.
The browser validator checks the container layer and runs entirely in the page, so a package containing confidential design work does not leave the machine. It answers whether the file is well formed. A package can pass every container check and still describe something no laboratory can build.
The reference validator answers the deeper questions. It runs three independent layers that must agree, structure against the JSON Schemas, semantics against the specification, and physics against the design rules, and it recomputes every acceptance verdict from the measured value, the comparator and the limit rather than trusting the recorded status.
| Command | What it does |
|---|---|
| python -m wwd component.wwd | Validate: container, structure, semantics. |
| python -m wwd component.wwd --schema | Cross-check the package against the published JSON Schemas, so schema and validator must agree. |
| python -m wwd component.wwd --dfm | Run the design rules: the DFM codes, which ask whether the design would work rather than whether the file is well formed. |
| python -m wwd component.wwd --conformance | Report which conformance classes the package reaches. |
| python -m wwd component.wwd --causal | Print the interventional projection of an as-built package: the controls, the context, the responses and the yield. |
| python -m wwd component.wwd --sample 6 1 0 | Evaluate every field at one point in the component frame. |
| python -m wwd component.wwd --rfq | Turn a specification into a supplier request for quotation. |
| python -m wwd *.wwd --corpus --learn | Stack several packages into a dataset and report what the accumulated builds say. |
The reference validator is Python 3.11 or later and uses the standard library only at runtime: no numpy, no jsonschema. An implementation in another language is verified against the published conformance suite of 64 vectors rather than against that Python.
What reads a .wwd file
Per the published documents.
| Tool | Behaviour | Opens a package |
|---|---|---|
| Any unzip tool | Reads it fully. The container is an ordinary ZIP archive buildable with the stock zip command, and every document inside it is JSON or a delegated payload format. | Yes |
| The browser validator on this site | Checks the container layer and reports the P0x diagnostic codes with severities and hints. Runs in the page; nothing is uploaded. | Yes |
| The Python reference validator | Three independent layers that must agree: JSON Schema structure, semantic validation, and design rules. Pure Python, standard library only at runtime. | Yes |
| A conforming third-party implementation | The specification publishes a portable conformance suite of 64 vectors with a manifest of the diagnostic codes a conforming validator must report for each one. The codes are normative; the message wording is not. | Where one exists |
| A CAD or slicer application | Does not read a .wwd package. Such tools read the delegated geometry or process parts a package may carry, for example a STEP body, a glTF preview or a 3MF print job, once those are extracted from the archive. | No |
Common findings when a package will not open
Diagnostic codes are normative, so two implementations reject a package for the same stated reason.
| Code | Condition |
|---|---|
| P01_NOT_ZIP | The file is not a readable ZIP archive. |
| P02_MIMETYPE_NOT_FIRST | The mimetype entry is not the first entry in the archive. |
| P02_MIMETYPE_CONTENT | The mimetype bytes are not exactly application/vnd.wwd+zip. |
| P03_NO_MANIFEST | There is no wwd/manifest.json. |
| P03_ROOT_MISSING | The manifest names a root design document that is absent from the package. |
| P05_INTEGRITY_MISMATCH | A payload does not match the SHA-256 digest the manifest declares for it. |
| P03_UNMANIFESTED | A payload file is present in the archive but absent from the manifest, so it carries no integrity guarantee. |
| P08_REQUIRED_EXT_UNSUPPORTED | The package requires an extension this implementation does not support, so semantic processing must be refused. |
All of these are errors. The code list is normative and a retired code is never reused.
- WWD file format reference. Definition, extension, media type, structure.
- Example packages. Seven files, shown field by field.
- The 0.1 draft specification, section by section.