Open specification · Draft 0.1
WWD, a file format for physical living components
One package carrying what a living component is, what it must do, and the method by which that is checked.
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, 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 article.
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.
Field model
The architectural decision the rest of the format follows from.
A wetware component is a shape plus a set of spatially varying property fields, and the fields are the design.
A model of a shape plus constant material properties, such as collagen I at 2.5 mg/ml, uniaxial, zero degrees, cannot express a stiffness gradient. Durotaxis requires one.
The quantities that determine tissue behaviour vary over the geometry. Representing them as attributes of the part rather than as functions over it removes the mechanism.
| Property | Value shape | Spatial variation |
|---|---|---|
| Cell density | Scalar | Seeding is not uniform. Core-versus-surface density is set by diffusion. |
| Fibre and cell alignment | Director + order parameter | A direction, not a number. It dominates contractile force along the axis. |
| ECM stiffness | Scalar | Cells migrate up stiffness gradients. A stiffness gradient is an instruction, not a tolerance. |
| Morphogen concentration | Scalar | Patterning is driven by the concentration gradient. A single number does not carry it. |
| Oxygen and nutrient availability | Scalar | Determines regional survival. Diffusion is a field problem; the necrotic core is its failure mode. |
| Co-culture composition | Composition vector | The fraction of each population varies regionally. |
| Porosity and pore size | Scalar | Governs vascular infiltration and cell migration, and is routinely graded. |
Two value spellings
The field machinery is an upgrade path. A first-time author does not 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. The property term, the target, the quantity kind, the provenance and the position of the value in the document are unchanged. Upgrading from uniform to spatially varying deepens one value.
{
"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.
{
"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: 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 returns this property's value at a given point and time.
Voxels are one backing: large, resolution-locked, and with no analytic gradient. WWD
defines one field abstraction with five ways of storing the values behind it, each
delegating to an existing format. 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 an escape hatch for a namespaced extension backing rather than a sixth
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.
Two statements about the same construct: "ECM stiffness rises from 10 kPa at the anchors to 16 kPa at midspan" and "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. The first is imposed by the producer. The second is produced by the tissue.
In wetware the manufacturer sets the conditions and the tissue produces the outcome. 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 | Meaning |
|---|---|---|
| control | designed | The protocol. The condition you intend to impose. |
| control | measured | The process log. The condition imposed. |
| 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. When a batch fails, the split distinguishes a protocol deviation from a biological response.
A ZIP container, from 0.1
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. 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.
Statistical acceptance criteria
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 not comparable between two suppliers. A method-less functional requirement is nonconformant.
Criteria declare which axis they test. A criterion on a control tests protocol execution. A criterion on a response tests the biological outcome.
{
"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" }
}Delegated vocabularies
WWD defines no cell types, no unit symbols, no geometry format and no array format.
A package declares each ontology by name, authoritative URI and release. A consumer must not silently substitute a different release: ontology deprecation must not change what a file recorded.
| Vocabulary | Coverage | Basis for delegation |
|---|---|---|
| Cell Ontology (CL) | Cell types, at the level a paper would state them. | Curated, versioned, and cited in the literature this format interoperates with. |
| NCBI Taxonomy | Source species. | The identifier every sequence database resolves against. |
| UBERON | Anatomical origin of the tissue or cell source. | Cross-species anatomy is already modelled there. |
| ChEBI | Small molecules: medium components, growth factors, cryoprotectants, drugs. | A medium formulation written as free text is not comparable between suppliers. ChEBI identifiers are. |
| UO and UDUNITS-2 | Units and quantity kinds. | Units are mandatory on every quantity in WWD. Both are machine-parseable and convertible. |
| Cellosaurus and RRID | Named established cell lines. | Cellosaurus tracks contaminated and problematic lines. A package pins the release it resolved against. |
| SBOL 3 | Genetic constructs and engineered sequence. | WWD references an SBOL identity and copies none of its sequence, feature or interaction semantics. |
| Format | Payload | Basis for delegation |
|---|---|---|
| STEP, 3MF, glTF/GLB, STL | Authoritative geometry and previews. | WWD states 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 and sits outside the container. |
| VTU, XDMF, glTF accessors | Mesh-attached field data. | Node-versus-cell association and interpolation rules are specified there. |
| CSV and Parquet | Sparse sampled tables, including electrode-site measurements. | Sparse measurements at named coordinates are stored without voxelisation. |
| NWB | Extracellular electrophysiology recordings. | A WWD channel map binds physical electrodes to NWB channel identities. |
| PROV-O | Lineage, chain of custody, agents and activities. | A W3C recommendation for provenance graphs. WWD maps onto it. |
Refusal rule: unknown-but-required is refused, not ignored. The manifest carries
extensionsUsed and extensionsRequired. 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 follows glTF
and SOAP.
Licensing
The specification text is CC BY 4.0 so it can be quoted, translated and reproduced in papers and in other standards. The schemas, reference validator, examples and conformance tests are Apache-2.0. Registry vocabularies are CC0.
Implementing WWD requires no permission and no fee. The licence covers this
documentation and this code. It says nothing about any device a .wwd file
happens to describe, which remains governed by whatever rights attach to that device.
Governance
Wetware World is the platform. WWD is the standard. They are separately named.
Wetware World is the format's author and its largest commercial implementer. Transfer to a
neutral custodian is planned. The protections in place until then are structural: the
licences are granted and irrevocable; the specification, schemas, validator, conformance
suite and examples are public, so no privileged implementation holds private knowledge;
and nothing in the format requires a service. A .wwd file is valid, parseable
and complete offline, with no call to any API.
Status and roadmap
Draft 0.1. Implementable, and expected to change.
| Version | State | Scope |
|---|---|---|
| 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. |
Current state
- No external implementers. One implementation, by Wetware World.
- No adopters, pilot users or committed suppliers accepting WWD files.
- No working group, consortium or standards-body relationship. Neutral custody is planned, not in place.
- The feature-discovery campaign with working laboratories has not been run.
- The property, interface, assay and shipping-state registries are thin. Registry mechanics are specified; breadth is deferred.
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.
Reference material
Examples, registries and comparisons.
- Seven example packages, each read field by field.
- Causal roles: control, response, context and derived, and what the validator refuses.
- Acceptance criteria: statistical acceptance, named assays, result rows, disposition and yield.
- As-built: designed, simulated and measured in one package, the realization, and what each column can be read for.
- Provenance: source material, passage, lot and realization, custody and commercial derivative rights, and the lineage from cell bank to measured result.
- Interfaces: mechanical and electrical ports, anchoring, ground ports, and the netlist that binds a tissue to a mechanism.
- Property fields: scalar-or-field slots, the five Core backings, and the registry field types.
- Geometry and payloads: named dimensions, delegation to 3MF and STL, the component frame, units, and the manifest record that carries a payload.
- Conformance: the 73 test vectors, what each asserts, the six conformance classes, and how a second implementation is tested.
- Validate a WWD file online: what the browser container check tests, every diagnostic code it emits, what it cannot test, and how to run the full validator instead.
- Design rules: the fifteen DFM checks the reference validator applies, each with its threshold, remedy and literature source.
- The Core registries: 58 property terms, 12 assay methods, 41 closed vocabularies.
- Glossary: every term the specification defines, with its section and the page that reads it in depth.
- The WWD Workbench: the application that opens, authors, validates, simulates and exports a package, with a session walked through.
- WWD against 3MF, 3MFBio, STEP, STL, SBML and SBOL.
Report a component the format cannot represent
Working laboratories are asked what the format fails to describe in their current process.