Format reference
Property fields
What a field is, how a constant becomes a gradient, the five backings and how each is stored, the registry terms with units and roles, and fields read out of the shipped packages.
Definition
In WWD, a field is a function assigning a value to each point in a declared spatial-temporal domain. A component is geometry plus regions plus spatially varying property fields. Every Core quantitative property slot is a scalar-or-field slot and accepts exactly two spellings: a quantity string such as "12 kPa", and a field object carrying an explicit backing discriminator. The quantity string is normative sugar for a constant field with the same number and unit, so upgrading a constant to a gradient changes no property identity, target or quantity kind. Core defines five backings: constant, expression, mesh_attribute, image_volume and table. Every field declares backing, property identity, quantity kind, unit, value type, frame, domain, interpolation, out-of-domain behavior and provenance, and every backing answers one operation, evaluate(x,y,z,t).
A component in WWD is a shape plus a set of spatially varying property fields. A field binds a property term to a component or a region, and states a domain over which the binding holds. A region whose membership cannot be resolved is an error wherever a required field uses it, and one property bound to overlapping regions with no stated precedence is an error as well.
Every region, field, interface, requirement, criterion, realization and result carries an identifier unique within the package. Every dimensional field carries a unit, and every field carries both a provenance class and a causal role.
Scalar to field
Two spellings of one semantic type.
The simple spelling is a quantity string: a finite number, whitespace, and a
UDUNITS-2-compatible unit expression. The rich spelling is a field object with an explicit
backing discriminator. A bare JSON number is invalid in a scalar-or-field
slot, and a JSON array alone is invalid in one too.
A quantity string is normative sugar for a constant field with the same
numeric value and unit. It has constant spatial interpolation, applies throughout the
target domain, has out-of-domain behavior error, and inherits the binding
provenance rather than defaulting silently. Canonicalization preserves numeric meaning,
unit meaning, property identity, target and provenance, and may convert the unit to the
canonical unit of the property. Upgrading a quantity string to a field object MUST NOT
change the property location, target, property identity or quantity kind.
{
"property": "wwd:ecm_stiffness",
"quantity_kind": "modulus",
"provenance": "designed",
"causal_role": "control",
"imposed_by": "protocol/gel-casting#step-2",
"value": "12 kPa",
"note": "set by collagen concentration and crosslink time"
}One stiffness over the whole strip, written as a quantity string.
{
"property": "wwd:ecm_stiffness",
"quantity_kind": "modulus",
"provenance": "designed",
"causal_role": "control",
"imposed_by": "protocol/gel-casting#step-2",
"value": {
"backing": "mesh_attribute",
"unit": "kPa",
"store": "fields/stiffness.vtu",
"association": "node",
"array": "stiffness",
"interpolation": "shape_function",
"domain": { "kind": "mesh" },
"out_of_domain": { "policy": "error" }
},
"note": "stiffness is graded along the strip: softer at the anchors, stiffer at midspan; the gradient is the design"
}
Same property term, same quantity kind, same target, same causal role and the same
protocol step imposing it. The value moved from a string to a mesh attribute stored in
fields/stiffness.vtu.
Common field contract
What every field declares, whatever its backing.
| Key | Level | Rule |
|---|---|---|
| backing | MUST | Which of the five Core backings supplies values, or a namespaced extension backing. |
| property identity | MUST | The registered property term the field binds. The field MUST NOT declare a quantity kind other than the one the registered term fixes. |
| quantity kind | MUST | Fixed by the registry for a registered term. |
| unit | MUST | Invariant over the domain. A field whose unit varies is reported as F13_UNIT_VARIES. |
| value type | MUST | Invariant over the domain. Scalar, vector3, unit_vector3, tensor, categorical, composition or alignment. |
| frame | MUST | The named frame the coordinates are read in. Any affine transform from backing coordinates into that frame MUST be declared. |
| domain | MUST | The spatial-temporal region over which the field is defined. |
| interpolation | MUST | Declared even when the answer is analytic, constant or none. |
| out-of-domain | MUST | Declared even when the answer is error. Default error. |
| provenance | MUST | designed, simulated, measured, inferred or assumed. A field with no provenance class is reported as F09_NO_PROVENANCE. |
| value support | MUST | Whether values are point values, node values, cell averages, regional averages or categorical memberships. |
| uncertainty | SHOULD | Identified as standard deviation, standard uncertainty, relative, confidence interval, tolerance interval or a referenced uncertainty field. |
| resolution hint | SHOULD | The smallest physical feature a consumer is expected to resolve. A consumer unable to meet a required hint MUST refuse the operation. |
| time dependence | MAY | A time-varying field MUST declare its temporal domain and interpolation. |
A field MAY carry missing values only where missingness semantics are explicit and distinct from numeric zero. Missing backing data inside the domain is a data error and is not ordinary out-of-domain behavior unless the missingness rules say so.
The five Core backings
How each stores its values in the container.
| backing | Storage | Rules |
|---|---|---|
| constant | Inline, no payload asset | One value matching the field value type, returned at every point in the domain. Interpolation is constant. It requires no spatial sampling lattice and MUST incur no requirement for a payload asset. It may carry scalar, vector, director, tensor, categorical or composition values. |
| expression | Inline analytic function | A deterministic analytic function of named inputs from x, y, z and t, read in the field frame and units, using only the closed function set of the applicable expression profile, aligned semantically with the safe mathematical node set of the 3MF Implicit extension. The graph MUST be acyclic. No file, network, environment, clock, random source or mutable state access. Undefined operations and non-finite results produce an evaluation error naming the offending expression. |
| mesh_attribute | Delegated mesh part, manifested with role field_data | A reference to a delegated mesh and a named attribute or accessor, with association node, cell, face, edge or quadrature, and a declared interpolation rule. Value and component counts MUST agree with mesh topology and association. The field frame MUST be consistent with the mesh frame or provide an explicit transform. VTK or XDMF are the delegated formats for simulation meshes and mesh-associated field data. |
| image_volume | Delegated image part, manifested with role field_data | A reference to OME-Zarr, OME-TIFF, NRRD or NIfTI content, identifying the array, channel or dataset, axis names, order, types and units, the complete mapping from array coordinates to physical field coordinates, node or cell centering, and interpolation nearest or linear. Categorical label volumes MUST use nearest-neighbor interpolation. A multiscale backing MUST fix which level governs evaluation, and the rule MUST NOT depend on viewport or client performance. |
| table | Inline when small, otherwise CSV or Parquet as a payload | Samples at explicit coordinates or explicit region identifiers, identifying coordinate columns, value columns, units, frame and missing-value representation, and whether each row is a point sample or a regional average. Interpolation is none, nearest, linear_in_simplex, inverse_distance, kriging or a namespaced extension method, and any method other than none MUST declare every parameter required for deterministic evaluation. Sparse MEA electrode values SHOULD use table. |
external is not a sixth Core backing. An unsupported representation is carried
as a namespace-qualified extension backing that participates in extension declaration and
refusal, and it still satisfies the common field contract and the evaluate contract. A
generic URI with no evaluation semantics is not a conforming field backing.
Value shapes
What one evaluation returns.
A scalar has one component and transforms invariantly under frame rotation. A
vector3 has three ordered components in the declared frame, and a
unit_vector3 has Euclidean norm one within declared tolerance; a zero vector
is not accepted as a unit vector or a director. A second-order tensor declares its kind,
its component ordering and its frame, with preferred symmetric order
xx, xy, yy, xz, yz, zz.
Uniaxial alignment is a unit director d and an order parameter S
in the closed interval [0,1], with normative meaning the orientation tensor
A = ((1 - S) / 3) I + S (d ⊗ d). The director is nematic, so d
and -d are equivalent and interpolation must respect that rather than
averaging signed vectors. An alignment field names the aligned structure and states
whether S is a 3D order parameter or a 2D planar one; a 2D value names its
measurement plane and frame. A composition maps identified constituents to nonnegative
fractions in unit 1, and declares whether the stored values are normalized.
{
"property": "wwd:fiber_alignment",
"quantity_kind": "order_parameter",
"provenance": "designed",
"causal_role": "response",
"structure": "sarcomeric_alpha_actinin",
"order_basis": "S2D",
"measurement_plane": "xy",
"director": [1.0, 0.0, 0.0],
"value": "0.72 1",
"note": "emerges from anchor geometry + stimulation; never imposed"
}
A uniform alignment: a constant director field and a constant S field. The
aligned structure is named, the order basis is the 2D planar parameter, and the
measurement plane is stated.
{
"property": "wwd:matrix_formulation",
"quantity_kind": "composition",
"provenance": "designed",
"causal_role": "control",
"imposed_by": "protocol/gel-casting#step-1",
"value": {
"backing": "constant",
"unit": "1",
"normalized": true,
"tolerance": 1e-06,
"constituents": { "collagen_i": 0.6, "fibrin": 0.4 }
},
"note": "proportions of the casting mixture"
}
Constituents carry stable identifiers, fractions carry unit 1, and the
field states that the stored values are normalized and to what tolerance.
Registry field types
62 Core terms. Each fixes a quantity kind, a canonical unit, a value shape and a causal class.
A field MUST NOT declare a quantity kind other than the one its registered term fixes, and MUST NOT declare a causal role contradicting the registered causal class. A consumer comparing two terms compares the quantity kind, not the unit text.
| Term | Quantity kind | Canonical unit | Value shape | Definition |
|---|---|---|---|---|
| wwd:anchor_spacing | length | mm | scalar | Distance between the mechanical anchors a tissue develops tension against. |
| wwd:coating_areal_density | areal_mass_density | ug/cm2 | scalar | Mass of adhesion coating applied per unit substrate area, such as laminin or fibronectin. |
| wwd:culture_co2_fraction | fraction | 1 | scalar | Volume fraction of carbon dioxide in the incubator or vessel headspace. |
| wwd:culture_oxygen_fraction | fraction | 1 | scalar | Volume fraction of oxygen in the incubator or vessel headspace. |
| wwd:culture_temperature | temperature | degC | scalar | Incubation temperature during culture. |
| wwd:ecm_stiffness | modulus | kPa | scalar | Elastic modulus of the extracellular matrix the cells are embedded in or plated on, as prepared. |
| wwd:electrode_count | count | 1 | scalar | Number of electrodes in the array serving one sampling unit. |
| wwd:electrode_diameter | length | mm | scalar | Diameter of one electrode's exposed contact area. |
| wwd:electrode_pitch | length | mm | scalar | Centre-to-centre spacing of adjacent electrodes in an array. |
| wwd:matrix_composition | categorical | 1 | categorical | Identity of the matrix formulation, by reference to a protocol or a ChEBI/vendor identifier. |
| wwd:matrix_concentration | mass_concentration | mg/mL | scalar | Total mass of matrix solids per unit volume of the cast mixture, before compaction. |
| wwd:matrix_formulation | composition | 1 | composition | Proportions of the identified constituents of the matrix, as nonnegative fractions summing to one. |
| wwd:mechanical_preload | force | uN | scalar | Static tension applied to a tissue before functional measurement. |
| wwd:medium_formulation | categorical | 1 | categorical | Identity of the culture medium formulation, by reference to a protocol or vendor catalogue identifier. |
| wwd:oxygen_tension | pressure | kPa | scalar | Partial pressure of oxygen in the culture environment. |
| wwd:photostimulation_irradiance | irradiance | mW/mm2 | scalar | Optical power per unit area delivered at the tissue surface. |
| wwd:photostimulation_wavelength | wavelength | nm | scalar | Peak wavelength of light delivered for optogenetic stimulation. |
| wwd:pillar_stiffness | spring_constant | uN/um | scalar | Lateral bending stiffness of a compliant post used to anchor a tissue and to read out its force from deflection. |
| wwd:print_nozzle_temperature | temperature | degC | scalar | Extrusion nozzle temperature during bioprinting. |
| wwd:recovery_duration | elapsed_time | h | scalar | Time a component is held under stated conditions after unpacking, before acceptance measurement. |
| wwd:seeding_density_areal | areal_density | cells/mm2 | scalar | Cell count per unit area of substrate at the moment of plating. |
| wwd:seeding_density_volumetric | number_density | cells/mL | scalar | Cell count per unit volume of a cast or cell-laden gel at the moment of casting. |
| wwd:stimulation_amplitude | electric_field_strength | V/cm | scalar | Applied field strength during electrical stimulation. |
| wwd:stimulation_duty_cycle | fraction | 1 | scalar | Fraction of the stimulation period during which the stimulus is on. |
| wwd:stimulation_frequency | frequency | Hz | scalar | Pulse repetition rate during electrical stimulation. |
| wwd:stimulation_pulse_width | signal_duration | ms | scalar | Duration of one stimulation pulse. |
| wwd:substrate_modulus | modulus | kPa | scalar | Elastic modulus of the non-living substrate or scaffold body the cells are plated on or cast against, as prepared. |
| Term | Quantity kind | Canonical unit | Value shape | Definition |
|---|---|---|---|---|
| wwd:active_electrode_fraction | fraction | 1 | scalar | Fraction of electrodes meeting a stated activity threshold. |
| wwd:burst_duration | event_duration | s | scalar | Duration of a single-electrode burst under the stated detection settings. |
| wwd:burst_rate | event_rate | 1/min | scalar | Rate of single-electrode bursts, averaged over the declared analysis population. |
| wwd:capillary_density | areal_density | 1/mm2 | scalar | Vessel count per unit cross-sectional area. |
| wwd:cell_alignment | order_parameter | 1 | alignment | Degree of cell-body alignment, expressed as for wwd:fiber_alignment. |
| wwd:compaction_ratio | ratio | 1 | scalar | Final dimension as a fraction of the as-cast dimension after cell-driven matrix remodelling. |
| wwd:conduction_velocity | velocity | cm/s | scalar | Propagation speed of an excitation wave across the construct. |
| wwd:contraction_frequency | frequency | Hz | scalar | Spontaneous contraction rate. |
| wwd:cross_sectional_area | area | mm2 | scalar | Area of the load-bearing cross-section, perpendicular to the axis along which force is developed and reported. |
| wwd:fatigue_retention | fraction | 1 | scalar | Fraction of initial force retained after a stated fatigue protocol. |
| wwd:fiber_alignment | order_parameter | 1 | alignment | Degree of fiber alignment expressed as a director plus an order parameter S in [0,1]. |
| wwd:half_relaxation_time | signal_duration | ms | scalar | Interval from peak twitch force to half of that peak during relaxation. |
| wwd:mean_firing_rate | frequency | Hz | scalar | Mean spike rate across analysed electrodes. |
| wwd:microbial_growth | categorical | 1 | categorical | Outcome of a sterility test: growth or no growth, under a stated medium, temperature and incubation period. |
| wwd:mycoplasma | categorical | 1 | categorical | Outcome of a mycoplasma test under a stated detection method. |
| wwd:network_burst_duration | event_duration | s | scalar | Duration of a network-wide synchronous burst, from the first to the last spike of the burst under the stated detection settings. |
| wwd:network_burst_participation | fraction | 1 | scalar | Fraction of electrodes taking part in a network burst. |
| wwd:network_burst_rate | event_rate | 1/min | scalar | Rate of network-wide synchronous bursts. |
| wwd:passive_tension | force | uN | scalar | Static tension a tissue develops against its anchors at rest, before stimulation. |
| wwd:peak_twitch_force | force | uN | scalar | Peak force of a single twitch contraction under a stated stimulation protocol. |
| wwd:purity | fraction | 1 | scalar | Fraction of cells expressing the stated identity marker set. |
| wwd:spontaneous_beat_rate | frequency | Hz | scalar | Spontaneous beat rate of a cardiac construct. |
| wwd:tetanic_force | force | uN | scalar | Peak force under fused tetanic stimulation. |
| wwd:time_to_peak_force | signal_duration | ms | scalar | Interval from stimulus onset to peak twitch force. |
| wwd:unloaded_shortening | ratio | 1 | scalar | Fractional shortening of an unloaded construct during contraction. |
| wwd:viability | fraction | 1 | scalar | Fraction of cells scored viable by a stated assay. |
| Term | Quantity kind | Canonical unit | Value shape | Definition |
|---|---|---|---|---|
| wwd:days_in_vitro | time | d | scalar | Days elapsed since plating or seeding, the conventional developmental clock for cultures. |
| wwd:differentiation_batch | categorical | 1 | categorical | Identifier of the independent differentiation run a population came from. |
| wwd:donor_id | categorical | 1 | categorical | Pseudonymous donor identifier. MUST NOT carry direct personal identifiers. |
| wwd:electrode_impedance | impedance | kohm | scalar | Electrode impedance magnitude at a stated frequency and in a stated electrolyte. |
| wwd:passage_number | count | 1 | scalar | Number of passages a population has undergone on receipt. |
| wwd:population_doublings | count | 1 | scalar | Cumulative population doublings a population has undergone. |
| wwd:reagent_lot | categorical | 1 | categorical | Lot identifier of a medium component, matrix, coating or supplement, as supplied. |
| wwd:transit_duration | elapsed_time | h | scalar | Time elapsed between despatch and unpacking. |
| Term | Quantity kind | Canonical unit | Value shape | Definition |
|---|---|---|---|---|
| wwd:specific_force | stress | kPa | scalar | Active force normalised by the cross-sectional area that generated it. |
The property registry in full, with domains and literature references
Fields in the shipped packages
Read out of the seven example archives.
| Package | Property | Spelling | Value | Role |
|---|---|---|---|---|
| muscle-strip-designed | wwd:ecm_stiffness | quantity string | 12 kPa | control |
| muscle-strip-highstiff | wwd:ecm_stiffness | quantity string | 20 kPa | control |
| graded-strip | wwd:ecm_stiffness | mesh_attribute | fields/stiffness.vtu, node association | control |
| graded-strip | wwd:matrix_formulation | constant, composition | collagen_i 0.6, fibrin 0.4 | control |
| graded-strip | wwd:fiber_alignment | quantity string plus director | S2D 0.72, d = [1, 0, 0] | response |
| bioprinted-strip | wwd:print_nozzle_temperature | quantity string | 22 degC | control |
| neurontile-asbuilt | wwd:seeding_density_areal | quantity string | 1500 cells/mm2 | control |
| neurontile-asbuilt | wwd:mean_firing_rate | quantity string | 2.5 Hz | response |
| pinwheel-study | wwd:pillar_stiffness | quantity string on the rig component | 2.4 uN/um | control |
graded-strip.wwd carries one extra archive member against the flat strip,
fields/stiffness.vtu, manifested with role field_data and a
SHA-256 digest. muscle-strip-designed.wwd and
muscle-strip-highstiff.wwd differ in one field value, 12 kPa against 20 kPa.
Evaluation
One operation, five backings.
Every conforming backing answers evaluate(x, y, z, t). The inputs
x, y and z are coordinates in the field frame and
spatial units, and t is a coordinate on the field time axis and unit. The
contract is semantic and prescribes no implementation API.
For identical package bytes, external asset bytes, query values and declared numerical precision, evaluation is deterministic. An evaluator documents its floating-point precision, supports at least IEEE 754 binary64 for Core arithmetic when used for acceptance or manufacturing, and never silently returns a non-finite value. Caching is permitted and must not change results.
| Step | Operation |
|---|---|
| 1 | Validate that the query lies in the declared field domain. |
| 2 | Map the query into backing coordinates using the declared transform. |
| 3 | Obtain samples or compute the expression according to backing semantics. |
| 4 | Apply the declared interpolation. |
| 5 | Return a value with the declared value type and unit. |
| Policy | Behavior |
|---|---|
| error | Evaluation fails at a query outside the domain. The default, and the policy a manufacturing or acceptance field should carry. |
| undefined | Propagates as missing. MUST NOT propagate as zero or false. |
| fallback | Returns a stated value, which MUST carry the field value shape and unit. A fallback with no value is reported as F11_NO_FALLBACK_VALUE. |
| clamp | Query is pinned to the domain bound. MUST identify the bounded backing axes it applies to. |
| wrap | Query wraps across the bounded axis. MUST identify the bounded backing axes it applies to. |
| mirror | Query reflects across the bounded axis. MUST identify the bounded backing axes it applies to. |
| nearest | Returns the value at the nearest represented coordinate. |
A result outside a registered physical range produces a validation error unless the
property definition permits it. Where a director is interpolated, the interpolation
respects d equivalent to -d. Where a composition is
interpolated, the result obeys the composition normalization rules.
Validation
The diagnostics a field can raise.
Field objects are closed objects: an unknown key inside one is refused rather than
ignored, because losing a key changes what the document says. A
WWD-Field-Evaluator implementation satisfies the scalar-or-field semantics,
the common contract and the evaluate contract for every backing it claims, lists the
backings it supports, and refuses evaluation of an unsupported required field.
| Code | Severity | Condition |
|---|---|---|
| C02_BARE_NUMBER | ERROR | A quantitative slot holds a bare number with no unit. |
| C02_BAD_QUANTITY | ERROR | A quantity string is malformed. |
| C02_BAD_VALUE | ERROR | A quantitative slot is neither a quantity string nor a field object. |
| F03_NO_BACKING | ERROR | A field object carries no backing discriminator. |
| F03_UNKNOWN_BACKING | ERROR | An unqualified backing outside the Core set. |
| F09_NO_PROVENANCE | ERROR | A scientific assertion declares no provenance class. |
| F13_UNIT_VARIES | ERROR | A field whose unit is not invariant over its domain. |
| F12_ATTRIBUTE_NOT_FOUND | ERROR | A field names an attribute the delegated mesh does not provide. |
| F12_COUNT_MISMATCH | ERROR | Attribute values do not match the mesh point or cell count. |
| F12_COMPONENT_MISMATCH | ERROR | An attribute array that does not divide evenly into its declared components. |
| F11_UNKNOWN_OOD_POLICY | ERROR | An out-of-domain policy a consumer cannot interpret. |
| F11_NO_FALLBACK_VALUE | ERROR | A fallback policy with no value, which substitutes a silent zero. |
| F11_BAD_TABLE_ROW | ERROR | A table backing whose rows cannot be read. |
| F11_ROW_WITHOUT_COORD | ERROR | A table row with no position, invented at the origin. |
| F11_ROW_WITHOUT_VALUE | ERROR | A table row with a position and nothing to return. |
| A8_RESPONSE_IMPOSED | ERROR | A response is expressed as a manufacturing instruction. |
| C05_OVERLAPPING_BINDING | ERROR | One property bound to overlapping regions, which states no precedence. |
| C03_NO_FRAME | WARNING | A spatial component declares no frame. |
Questions
What is a property field in a WWD file?
A field is a function assigning a value to each point in a declared spatial-temporal domain. It binds a property term to a component or region, and it states a quantity kind, a unit, a value type, a frame, a domain, an interpolation rule, an out-of-domain policy, a provenance class and a causal role.
How does a scalar become a field?
By replacing the quantity string with a field object. A quantity string is normative sugar for a constant field with the same numeric value and unit, with constant interpolation, applying throughout the target domain, with out-of-domain behavior error. Upgrading from a quantity string to a field object MUST NOT change the property location, target, property identity or quantity kind.
What field backings does WWD define?
Five: constant, expression, mesh_attribute, image_volume and table. A backing outside that set must be namespace-qualified and declared as an extension. external is not a sixth Core backing, and a generic URI with no evaluation semantics is not a conforming field backing.
Why does a bare number fail in a field slot?
A bare JSON number MUST NOT serve as a dimensional quantity in a Core scalar-or-field slot, and a JSON array alone is invalid in the same slot. A validator reports the first as C02_BARE_NUMBER and a slot that is neither a quantity string nor a field object as C02_BAD_VALUE. Dimensionless values use the unit 1.
How is an alignment field stored?
As a unit director d and an order parameter S in the closed interval [0,1], with the field naming the aligned structure and whether S is a 3D order parameter or a 2D planar one. The director is nematic, so d and -d are equivalent. Bare angles MUST NOT be the sole stored representation of a discrete alignment field, and quaternions MUST NOT be the primary stored alignment representation.
What happens outside a field domain?
The declared out-of-domain policy applies. Core policies are error, undefined, fallback, clamp, wrap, mirror and nearest. The default is error, a producer MUST NOT rely on an implicit fallback of zero, and a fallback policy MUST carry a value with the field value shape and unit. A field used in manufacturing or acceptance SHOULD use error.
Continue
Related pages.
- The WWD file format. Container, manifest, design and results documents.
- The Core property registry. Every term with its domain and reference.
- Seven example packages, each read field by field.
- The WWD 0.1 draft specification. All normative sections with anchors.
- Downloads. Example packages and JSON Schemas.