Open specification · Draft 0.1
WWD — a file format for physical living components
You can buy a printed circuit board by uploading a file. Nobody can buy a piece of engineered tissue that way, because there is no file to upload. WWD is an attempt at that missing artefact: one package carrying what a living component is, what it must do, and how anyone would check.
What WWD is
An interchange and manufacturing-article description. Not a product, not a solver, not an ontology.
Cells, media, scaffolds and reagents are already catalogue items. Finished living tissue with a specification — this geometry, these cells, this alignment, this force, verified by this assay — still moves between laboratories as a PDF, an email thread and a phone call. Two suppliers quoting the same muscle strip are not quoting the same thing, and nobody involved can tell.
WWD binds biological identity, geometry, regions, property fields, interfaces, requirements, results and provenance into one identified article description. The JSON inside it is a binding and manifest layer only: geometry, images, arrays, recordings, solver decks and assay payloads are delegated to formats that already exist and are already maintained.
A WWD design stays valid and conformant with no simulation content in it at all. A simulated value may never be represented as a measured one, and a measured value never overwrites the as-designed value it was compared against.
The field-first thesis
The one architectural decision everything else follows from.
A wetware component is not a shape plus a material. It is a shape plus a set of spatially varying property fields — and the fields are the design.
The first version of this format modelled a component the way a machinist would: a shape, plus constant material properties. Collagen I at 2.5 mg/ml, uniaxial, zero degrees. It was scrapped on the day it was written, because it fails the first time anyone asks for a stiffness gradient — and a stiffness gradient is not an exotic request. It is how durotaxis works.
Everything that makes tissue behave like tissue varies over the geometry. Treating those quantities as attributes of the part rather than functions over it is not a simplification. It deletes the mechanism.
| Property | Value shape | Why it varies over space |
|---|---|---|
| Cell density | Scalar | Seeding is never perfectly uniform, and core-versus-surface density is decided by diffusion long before anyone measures it. |
| Fibre and cell alignment | Director + order parameter | A direction, not a number. It dominates contractile force along the axis and is the reason two constructs of identical composition produce different force. |
| ECM stiffness | Scalar | Cells migrate up stiffness gradients. A stiffness gradient is therefore an instruction, not a manufacturing tolerance. |
| Morphogen concentration | Scalar | A concentration gradient is how biology patterns itself. Collapsing it to one number deletes the mechanism. |
| Oxygen and nutrient availability | Scalar | Decides what survives where. Diffusion is intrinsically a field problem and the necrotic core is its failure mode. |
| Co-culture composition | Composition vector | The fraction of each population varies regionally. One number for "70:30" describes a beaker, not a construct. |
| Porosity and pore size | Scalar | Governs vascular infiltration and cell migration, and is routinely graded deliberately. |
The convergent-evolution argument: anyone building a serious version of this format will independently discover they need spatial fields, because tissue engineering is field engineering. If the field model is right at 0.1, a better competing format converges on the same structure rather than replacing it.
Simple stays simple
The field machinery is an upgrade path, never a tax. A first-time author must never meet it to place an order.
A quantitative property slot accepts exactly two spellings. The simple one is a quantity
string: a number and a UDUNITS-2 unit expression. The rich one is a field object carrying
an explicit backing discriminator. They are two representations of one
semantic type, not two property types — the quantity string is normative sugar for a
constant field with the same value and unit.
Below is the same property on the same component, written both ways. Note what does not change: the property term, the target, the quantity kind, the provenance, and the position of the value in the document. Upgrading from uniform to spatially varying deepens one value. It does not restructure anything around it.
{
"property": "wwd:ecm_stiffness",
"quantity_kind": "modulus",
"provenance": "designed",
"causal_role": "control",
"imposed_by": "protocol/gel-casting#step-2",
"value": "12 kPa"
}Twelve kilopascals everywhere in the domain. A bare JSON number here is a hard validation error, not a warning: half the interchange failures in this domain are a number whose unit lived in a column header that got lost.
{
"property": "wwd:ecm_stiffness",
"quantity_kind": "modulus",
"provenance": "designed",
"causal_role": "control",
"imposed_by": "protocol/gel-casting#step-2",
"value": {
"backing": "expression",
"unit": "kPa",
"frame": "component",
"inputs": ["x"],
"expression": "10 + 6 * (1 - abs((x - 6) / 6))",
"domain": "region/active",
"interpolation": "analytic",
"out_of_domain": "error"
}
}
Ten kilopascals at each anchor rising to sixteen at midspan, as a closed-form function of
the component frame. Out-of-domain behaviour defaults to error, never a
silent zero.
Precedent for the pattern: OpenUSD primvars, which carry constant, uniform, varying and
vertex interpolation under one attribute; and CSS, where color: red and a
gradient occupy the same declaration.
Five backings, one evaluation contract
Every field answers the same question: what is this property's value at this point, at this time.
Voxels are one backing and a poor default — large, resolution-locked, and with no analytic
gradient. So WWD defines one field abstraction with five ways of storing the values behind
it, each delegating to something that already exists. Every backing must answer
evaluate(x, y, z, t) in the field's declared frame and units, and every one is
referenceable by URI so that heavy data can sit outside the archive.
| Backing | Definition |
|---|---|
| constant | One value over the whole domain. The degenerate case, and the one a quantity string canonicalises to. Requires no payload asset at all. |
| expression | A deterministic analytic function of x, y, z and t drawn from a closed function set aligned with the 3MF Implicit node set. No arbitrary code, no file or network access, no randomness, no clock. This is the anti-voxel default. |
| mesh_attribute | Values attached to a delegated mesh, declaring node, cell, face, edge or quadrature association and the interpolation rule that goes with it. |
| image_volume | Values read from OME-Zarr, OME-TIFF, NRRD or NIfTI, with the complete array-to-physical mapping declared. Categorical label volumes must use nearest-neighbour; linear interpolation of a label is a category error the format refuses. |
| table | Sparse samples at explicit coordinates or named regions, declaring whether each row is a point sample or a regional average, plus a named interpolation rule with all its parameters. |
external is not a sixth backing. It is an escape hatch for a namespaced
extension backing, and it still has to satisfy the common field contract and the evaluation
contract. A bare URI with no evaluation semantics is not a conforming field.
Two tags on every number
Provenance says where a value came from. Causal role says who or what determined it.
Consider two statements about the same construct. "ECM stiffness rises from 10 kPa at the anchors to 16 kPa at midspan." "Fibre alignment rises from S = 0.60 at the anchors to S = 0.80 at midspan." Structurally these are identical: same backing, same units discipline, same domain, both designed. Causally they are opposites. The first is something the producer imposes. The second is something the tissue does. You cannot pipette alignment.
Every manufacturing exchange format written so far assumes the manufacturer causes the
outcome, because for metal it does. In wetware the manufacturer causes the conditions and
the tissue causes the outcome. So WWD carries two orthogonal required tags on every
scientific assertion: provenance — designed, simulated, measured, inferred or
assumed — and causal_role — control, response, context or derived.
| causal_role | provenance | What it is in practice |
|---|---|---|
| control | designed | The protocol. The condition you intend to impose. |
| control | measured | The process log. The condition actually imposed, which is not the same thing. |
| response | designed | The target. What you want the tissue to become. |
| response | simulated | The prediction. What your model says it will become. |
| response | measured | The result. What it became. |
| context | measured | The covariate. Donor, passage number, transit excursion. |
| derived | inferred | Statistics, aggregates, calibrated parameters. |
Protocol, process log, specification, prediction, result, covariate and statistic are not seven schema branches. They are one field object under seven tag combinations, which is the main reason the format stays small while covering a large surface. The practical version, for a laboratory with no interest in causal inference: when a batch comes out wrong, this split is what answers did we do it differently, or did the cells respond differently. Those have completely different remedies, and today the answer lives in a technician's memory.
A ZIP container, from 0.1
Not a flat JSON file. Real orders carry STEP bodies, microscopy stacks and force traces.
A conforming package is an ordinary ZIP archive whose first entry is an uncompressed
mimetype file containing exactly application/vnd.wwd+zip — the
magic-number rule EPUB and ODF use, so file-type detection works without unpacking. One
wwd/manifest.json unifies content types, relationships and a BagIt-style file
manifest with byte lengths and SHA-256 integrity for every payload. The archive is
buildable with the stock zip command and inspectable with any unzip tool.
Assets too large to embed link out by URI with byte length and content hash. An OME-Zarr store is a directory of chunks designed for partial cloud reads and can run to tens of gigabytes; it cannot live inside an archive, and pretending otherwise would make the format unusable for exactly the people it is for. The URI is a retrieval location. The hash is the identity.
MuscleStrip-10.wwd (a ZIP archive; open it with any unzip tool)
├── mimetype application/vnd.wwd+zip, stored, first entry
└── wwd/
├── manifest.json contents, roles, byte lengths, sha256 integrity
├── design.json the component: geometry refs, regions, fields,
│ interfaces, acceptance criteria
└── results.json measured results, present only once built
data/twitch.csv assay evidence, manifested and hashed
process/print-job.3mf delegated process deck, carried opaquely{
"wwd": "0.1",
"mediaType": "application/vnd.wwd+zip",
"package_id": "urn:uuid:9fd92e84-0000-4000-8000-000000000000",
"root": "wwd/design.json",
"extensionsUsed": [],
"extensionsRequired": [],
"files": [
{
"name": "wwd/design.json",
"mediaType": "application/vnd.wwd.design+json",
"bytes": 6153,
"integrity": "sha256-8RWgPNKzIS2BQuqdZJSAWneAwakvimAg7mc+imGWq3w=",
"role": "design"
},
{
"name": "data/twitch.csv",
"mediaType": "text/csv",
"bytes": 92,
"integrity": "sha256-iqEhDjrB3H9ps3y5jZr088uchyCpx7HVpOlxPYQ+ZAs=",
"role": "assay_evidence"
}
],
"external": [],
"relationships": [
{ "type": "org.wwd.rel.results",
"source": "wwd/design.json", "target": "wwd/results.json",
"mode": "internal" }
]
}
There is no mode flag. As-built is derived, not declared:
as_built := measured_results is nonempty. Appending results never mutates the
acceptance criteria they were tested against, and lot disposition is derived from criteria
and results rather than stored as an unexplained fact.
Specifications are statistical, or they are meaningless
And every functional number carries the assay that produced it.
"500 µN twitch force" is not a specification for a stochastic biological product. "Median
at least 500 µN, CV no greater than 0.20, n = 12, one-sided at α = 0.05" is. WWD encodes
that as two linked criteria — location and dispersion are never one compound statistic —
each with an immutable UUID, a closed statistic and comparator
vocabulary, an optional sampling plan, and an optional decision rule distinguishing a
point estimate from a test, a confidence bound and a tolerance interval.
The assay method is mandatory. A force value without a stated test method, temperature, stimulus, preload and fixture is uncomparable between two suppliers, which defeats the entire purpose of the file existing. A method-less functional requirement is nonconformant, not merely poor practice.
Criteria also declare which axis they test. A criterion on a control asks did we execute the protocol. A criterion on a response asks did the biology deliver. Today both are "the batch failed", and conflating them is how process drift hides behind biological variability.
{
"tag": "AC-001",
"title": "Median twitch force",
"target": "region/active",
"measurand": { "quantity": "peak_twitch_force", "unit": "uN" },
"statistic": "median",
"comparator": ">=",
"limit": 500,
"criticality": "critical",
"tests_axis": "response",
"method": {
"id": "WWD-TWITCH-001",
"protocol_ref": "protocol/twitch.md",
"conditions": { "temperature_c": 37, "stimulus_hz": 1, "preload_mn": 0.5 }
},
"sampling": { "n": 12, "selection": "random", "destructive": true },
"decision_rule": { "kind": "test", "alpha": 0.05, "sided": "one" }
}Never mint a vocabulary that already exists
WWD defines no cell types, no unit symbols, no geometry format and no array format.
This is a hard rule, not a preference. Inventing a cell-type vocabulary when the Cell Ontology exists is the fastest way for a format to be dismissed by the people whose files it needs. A package declares each ontology by name, authoritative URI and release, and a consumer must not silently substitute a different release: ontology deprecation must never change what a file recorded.
| Vocabulary | What it covers | Why we did not reinvent it |
|---|---|---|
| Cell Ontology (CL) | Cell types, at the level a paper would state them. | CL is curated, versioned, and already cited in the literature this format has to interoperate with. Minting a competing cell-type list is the fastest way to be dismissed by the people who would have to use it. |
| NCBI Taxonomy | Source species. | Universal, stable, and already the identifier every sequence database resolves against. |
| UBERON | Anatomical origin of the tissue or cell source. | Cross-species anatomy is a solved and thankless problem. It stays solved elsewhere. |
| ChEBI | Small molecules: medium components, growth factors, cryoprotectants, drugs. | A medium formulation written as free text is not comparable between two suppliers. ChEBI identifiers are. |
| UO and UDUNITS-2 | Units and quantity kinds. | Units are mandatory on every quantity in WWD. A unit system that a machine can already parse and convert is worth more than one we invented. |
| Cellosaurus and RRID | Named established cell lines. | Line identity is where misidentification lawsuits and retractions come from. Cellosaurus already tracks contamination and problematic lines; a package pins the release it resolved against. |
| SBOL 3 | Genetic constructs and engineered sequence. | Synthetic biology has spent fifteen years on this. WWD references an SBOL identity and copies none of its sequence, feature, or interaction semantics. |
| Format | What it carries | Why we did not reinvent it |
|---|---|---|
| STEP, 3MF, glTF/GLB, STL | Authoritative geometry and previews. | A living component is still a shape, and CAD already has shapes. WWD says which body is authoritative and which is a preview. |
| OME-Zarr 0.5, OME-TIFF, NIfTI, NRRD | Image volumes backing image-derived fields. | A microscopy stack is tens of gigabytes of chunked cloud-read data. It does not belong inside a container and does not need reinventing. |
| VTU, XDMF, glTF accessors | Mesh-attached field data. | Node-versus-cell association and interpolation rules are already specified there. Guessing them is how field data silently becomes wrong. |
| CSV and Parquet | Sparse sampled tables, including electrode-site measurements. | Sparse measurements at named coordinates should not be voxelised just to have a home. |
| NWB | Extracellular electrophysiology recordings. | Neuroscience settled this. A WWD channel map binds physical electrodes to NWB channel identities and stops there. |
| PROV-O | Lineage, chain of custody, agents and activities. | A provenance graph model already exists with a W3C recommendation behind it. WWD maps onto it rather than beside it. |
The corollary is a refusal rule. Unknown-but-required is refused, not ignored: the manifest
carries extensionsUsed and extensionsRequired, and a consumer that
does not support a required extension must refuse semantic processing and name every
unsupported extension before manufacture, simulation, acceptance or conversion. The pattern
is glTF's and SOAP's, for the same reason both adopted it.
Open, and deliberately unpatented
Chosen before adoption rather than after, because retroactive relicensing with outside contributors is miserable.
The format is not patented and will not be. Two reasons, in order of importance. First, a patented format does not get adopted, and a format nobody adopts is worth nothing to anybody including its author. Second, abstract data structures are largely unpatentable in the United States regardless, under Alice v. CLS Bank and 35 U.S.C. §101, so the attempt would buy an expensive and fragile claim.
The durable split is free format, protected implementation. This is the ARM model: the instruction set documentation is open, the silicon is licensed. Publishing the format costs nothing that is worth keeping and buys the only thing that matters, which is other people using it.
Note the boundary carefully. The Apache-2.0 patent grant on the schemas and validator
covers claims necessarily infringed by that work — this code and these schemas.
It conveys no rights over separately patented apparatus that a .wwd file
merely describes. Implementing WWD is free. Building a particular device is a different
question, governed by that device's own patents.
Governance, and the lesson we are copying from PCB
Wetware World is the platform. WWD is the standard. They are separately named on purpose.
ODB++ was, by any operational measure, generous: free specification, free viewer, free tooling, free support, tens of thousands of users. It was also vendor-owned, and that is precisely why the industry funded IPC-2581 as a neutral competitor. Nobody objected to the quality. They objected to the structure — a format whose continuation rests on the current management of a company that is also the largest commercial implementer.
Wetware World would be in exactly that position. So the neutral-foundation path is planned
early rather than improvised under pressure. The protections that hold in the meantime are
structural, not promissory: the licences are already granted and are irrevocable; the
specification, schemas, validator, conformance suite and examples are all public, so there
is no privileged implementation with private knowledge; and nothing in the format requires
a service. A .wwd file is valid, parseable and complete offline, forever, with
no call to anyone's API.
The target end state is competitors saying "we accept WWD files". That is a win only if governance is credibly neutral before anyone has to demand it.
The moat is the validator, the design-for-manufacture rules, the supplier network and the round-trip corpus — not the schema. A file format with one implementer is just a data structure. Which is why the format is given away and the work around it is not.
Status and roadmap
Draft 0.1. Real enough to implement against, explicitly expected to change.
| Version | State | What it means |
|---|---|---|
| 0.1 | Draft, current | Implementable and explicitly breakable. Twenty-five normative sections, a JSON Schema set, a reference validator and a conformance suite. Nothing is frozen. |
| 0.2 | Not started | Written after 50 to 100 real designs have been pushed through 0.1. That traffic is the only thing that reveals which fields were wrong, and there is no substitute for it. |
| 1.0 | Not scheduled | Core vocabulary frozen, additive change only afterwards. Reached only once the core has survived several suppliers and several tissue types. Freezing early is worse than not freezing. |
What is not true yet
- There are no external implementers. One implementation is ours, and a format with one implementer is a data structure.
- There are no adopters, no pilot users and no committed suppliers accepting WWD files.
- There is no working group, no consortium and no standards-body relationship. The neutral-custody path is a plan, not a fact.
- The researcher feature-discovery campaign — asking working laboratories what they actually need represented — has not been run. Until it has, parts of this draft are informed guesses.
- The property, interface, assay and shipping-state registries are deliberately thin. Registry mechanics are specified; breadth is deferred until real traffic says what belongs in them.
The version lives inside the file, in "wwd": "0.1", and never in the extension.
A .wwd written today and one written in ten years are both .wwd.
Tell us what it cannot represent
The most useful thing anyone can send a draft standard is a component it fails to describe. We are asking working laboratories what breaks in their process today, not whether they would buy something.