Format reference
As-built
Designed, simulated and measured in one package, kept apart. The realization that links a lot to its design revision, the carriage rules for a study on an article nobody has built, and the codes that refuse a prediction dressed as a measurement.
Definition
A WWD package carries designed, simulated and measured content in one file without collapsing them. Every field, state value, model input, model output, acceptance criterion target and result MUST declare a provenance class, and the Core classes are designed, simulated, measured, inferred and assumed. Measured content MUST identify an assay or observation activity, simulated content MUST identify a model run, and designed content SHOULD identify authoring agent and revision. A package with no measured results is as-designed. A package with one or more measured results is as-built in addition to carrying its unchanged design, and mode MUST be derived as as_built := measured_results is nonempty rather than stored. Every realization MUST have an identifier, MUST declare its identifier scheme and MUST reference the exact component design revision realized. A package with no realization MAY carry a results document holding only simulation content, and that content MUST NOT make the package as-built. A result MUST NOT copy a simulated value into the measured-results collection.
One quantity can appear three times in one file. Peak twitch force is a designed target of 550 uN, a simulated output of 648 uN and a measured median of 612 uN. The three are the same property term, the same unit and the same causal role, and they are three different claims. WWD separates them on the provenance axis, and the separation is carried on the assertion rather than inferred from where the number sits.
Design and as-built live in the same package. The design document is unchanged by the arrival of results, and the results document names the realization the measurements were taken on.
The provenance classes
What each one may claim and what it may not.
| Class | The assertion is | May claim | May not claim | Identification |
|---|---|---|---|---|
| designed | What the producer asked for. A control value the protocol will impose, or a response target the tissue is asked to reach. | That this is the intent carried by design revision 1.3.0. | That any article exists, that any article reached the value, or that a model predicted it. | SHOULD identify authoring agent and revision. |
| simulated | What a model returned. An output of one run of one model over the design. | That the named solver, at the named version, over the named model, produced this number. | That a physical article behaved this way. It MUST NOT satisfy a measured acceptance criterion. | MUST identify a model run, and MUST reference exactly one run present in the package. |
| measured | What an assay read off a physical realization. | That the named observation activity produced this value on the identified realization or specimens. | That the value holds for a different design revision, a different lot, or a statistic the criterion does not name. | MUST identify an assay or observation activity. |
| inferred | A value computed from other content by an inference activity. | That the stated source entities and inference activity produce it. | To stand as a measurement of the sources it was inferred from. | MUST identify source entities and inference activity. |
| assumed | A value taken as given with no assay, run or derivation behind it. | Only itself. | To be read as evidence of any kind. | SHOULD state rationale. |
A provenance class is not a confidence score. A consumer MUST present or expose these classes distinctly.
The realization
What links a lot to the design it was made against.
A realization identifies a physical specimen, unit, batch or lot made against a design revision. Acceptance criteria belong to the design. Measured results belong to identified realizations. Every measured result MUST identify the realization or specimens observed and MUST reference exactly one acceptance criterion UUID that resolves within the package design context.
A component MUST NOT be both a design definition and a physical realization under one identifier. The design revision on the realization MUST match the design carried in the package, so a measurement is never attributed to a revision it was not taken against.
{
"id": "lot/WW-2026-0142",
"scheme": "local",
"design_revision": "1.3.0",
"manufactured": "a date"
}Lot WW-2026-0142 under the local identifier scheme, made against design revision 1.3.0. The design document in the same package is at that revision.
{
"id": "mr-0001",
"criterion": "3f7c2a9e-51b4-4c1e-9a77-0d2f8e6b1c44",
"status": "pass",
"value": 612,
"unit": "uN",
"statistic": "median",
"n_observed": 12,
"provenance": "measured",
"causal_role": "response",
"observation_activity": "activity/twitch-assay",
"raw_data": "data/twitch.csv"
}One criterion UUID, one status, one statistic, an observed sample size, an observation activity and the raw data carried in the package.
| Key | Status | Value in the example | Rule |
|---|---|---|---|
| id | required | lot/WW-2026-0142 | Identifies the physical specimen, unit, batch or lot. An as-built package with no realization identifier is R05_NO_REALIZATION. |
| scheme | required | local | One of local, vendor.lot, gs1.gtin, gs1.lot, isbt128.din, isbt128.coi. An opaque string is not resolvable and a lot number is unique only within the facility that issued it. Absence is R05_NO_ID_SCHEME. |
| design_revision | required | 1.3.0 | The exact component design revision realized. It MUST match the design carried in the package. Absence is R05_NO_DESIGN_REVISION. |
| manufactured | optional | a date | When the article was made. A realization MUST NOT be dated before the activities in its own lineage, reported as T03_BUILT_BEFORE_ITS_HISTORY. |
| lot | optional | a lot string | Lot, batch, specimen, serial or donation identification where applicable. |
Mode is derived, never stored: as_built := measured_results is nonempty. A
design document carrying a mode key is refused. A draft package MUST NOT
declare a realization or carry measured results, because a lot either exists or does not.
A study on an article nobody has built
Section 18.5 carriage, against a measured lot record.
A model or run MAY be carried in either of two places, and a consumer MUST read both. A
package reporting simulation outputs carries simulation_models and simulation_runs in the results document, beside the simulation_results that depend on them. A design carrying a study it has not
yet run carries models and runs in the design document. The same
identifier MUST NOT appear in both places.
A package with no realization MAY carry a results document holding only simulation
content. That document MUST NOT declare a realization and MUST NOT carry measured results,
and its presence MUST NOT make the package as-built: as-built is keyed on the realization,
and a prediction is not a lot. Its manifest role is simulation_result, not measured_result_data. The test suite carries this as valid-design-only-study, which reaches WWD-Design-Core and WWD-Package-Core and not WWD-As-Built.
| Case | Model and run | Outputs | Realization | Manifest role | Mode |
|---|---|---|---|---|---|
| A design nobody has built | models and runs in the design document | simulation_results, with simulation_models and simulation_runs, in the results document | None. The document MUST NOT declare a realization and MUST NOT carry measured results. | simulation_result | Stays as-designed. The presence of predictions MUST NOT make the package as-built. |
| A built lot | No model is required | simulation_models and simulation_runs beside the simulation_results that depend on them | A realization with an identifier, a scheme and a design revision | measured_result_data | as_built is derived from measured_results being nonempty. |
{
"id": "sr-0001",
"run": "run/fea-001",
"quantity": "peak_twitch_force",
"value": 648,
"unit": "uN",
"frame": "component",
"provenance": "simulated",
"causal_role": "response",
"domain": "region/whole"
}
648 uN from run run/fea-001, FEBio 4.4.2,
over model model/fea-contraction, which interprets design revision 1.3.0. The run declares completion and convergence as two separate facts.
What the validator refuses
Code, trigger, and the change the writer makes.
A simulated output MUST have simulated provenance and reference exactly one run. A
measured output MUST have measured provenance and reference an observation activity. A
result MUST NOT copy a simulated value into the measured-results collection. The reference
validator reads each row of measured_results, and a row declaring provenance simulated raises F09_SIMULATED_AS_MEASURED and is not processed
further against its criterion.
| Code | Severity | Trigger | Change |
|---|---|---|---|
| F09_SIMULATED_AS_MEASURED | ERROR | A row in measured_results declares provenance simulated. | Put the value in a simulation result linked to its run. A simulated value MUST NOT satisfy a measured acceptance criterion. |
| F09_BAD_RESULT_PROVENANCE | ERROR | A row in measured_results declares a provenance other than measured. | Declare provenance measured, or move the row out of measured_results. |
| F09_NO_PROVENANCE | ERROR | A scientific assertion declares no provenance class. | Add provenance: designed, simulated, measured, inferred or assumed. There is no default. |
| R05_NO_OBSERVATION | ERROR | A measured result names no observation_activity, or an as-built package with criteria carries no measurement array. | Name the activity that produced the number. |
| R05_NO_REALIZATION | ERROR | An as-built package carries no realization identifier. | Add realization.id naming the specimen, unit, batch or lot observed. |
| R05_NO_ID_SCHEME | ERROR | The realization declares no scheme. | Declare scheme: local, vendor.lot, gs1.gtin, gs1.lot, isbt128.din or isbt128.coi. |
| R05_GTIN_NOT_A_UNIT | ERROR | The realization scheme is gs1.gtin. | Use gs1.lot, vendor.lot or local. A GTIN identifies a product type, not an individual unit. |
| R05_VENDOR_LOT_NO_ISSUER | WARNING | The scheme is vendor.lot and no organization agent is declared in the provenance graph. | Add the supplier as an organization agent. |
| R05_NO_DESIGN_REVISION | ERROR | The realization pins no design revision. | Set design_revision to the exact revision realized. |
| R04_DANGLING_CRITERION | ERROR | A measured result references a criterion the package does not contain. | Point the result at an existing acceptance criterion UUID. |
| R06_AUTHORED_MODE_FLAG | ERROR | The design document carries a mode key. | Remove it. As-built mode is derived from the presence of measured results. |
| W02_DRAFT_WITH_RESULTS | ERROR | A manifest marked draft carries a realization or measured results. | Clear the draft flag, or remove the lot record. A lot either exists or does not. |
| Q02_SIMRESULT_DANGLING_RUN | ERROR | A simulation result references a run the package does not contain. | Carry the run, in the design or beside the results. |
| Q01_RUN_DANGLING_MODEL | ERROR | A run references a model the package does not contain. | Carry the model in the same package. |
| Q07_MODEL_NO_REVISION | ERROR | A model identifies no component or design revision it interprets. | Name the component and the design revision the model interprets. |
| Q09_ENVELOPE_DUPLICATED | ERROR | The same model or run identifier is carried both in the design and beside the results. | Keep one copy. Either place is permitted, both are not. |
| Q05_CONVERGENCE_UNDECLARED | ERROR | A run reports completion and no convergence status. | Declare completion status and convergence status as two separate facts. |
| Q06_UNCONVERGED_AS_SUCCESS | ERROR | A run that completed without converging is reported as a successful simulation. | Record the run as unconverged. |
Moving sr-0001 from simulation_results into measured_results is the test-suite vector invalid-simulated-as-measured. In its own block the same object conforms.
One quantity, three columns
Taken from muscle-strip-designed.wwd, simulated-strip.wwd and muscle-strip-asbuilt.wwd.
| Quantity | Role | Designed | Simulated | Measured | Statistic | n | Assay | Observation activity |
|---|---|---|---|---|---|---|---|---|
| peak_twitch_force | response | 550 uN | 648 uN | 612 uN | median | 12 | WWD-TWITCH-001 | activity/twitch-assay |
| fiber_alignment | response | 0.72 1 | - | 0.71 1 | median | 5 | WWD-ALIGN-001 | activity/imaging |
| ecm_stiffness | control | 12 kPa | - | 12.4 kPa | value | - | WWD-RHEO-001 | activity/rheometry |
Peak twitch force carries all three. Fiber alignment and ECM stiffness carry a designed and a
measured value and no prediction, because the model in simulated-strip.wwd
returns peak twitch force and unloaded shortening only. Unloaded shortening, at 0.081 1, is a simulated
value with no designed target and no criterion, so it has no measured column at all.
| Column | Package | Contents | Supports | Does not support |
|---|---|---|---|---|
| designed | /wwd/examples/muscle-strip-designed.wwd | The value the producer asked for, under revision 1.3.0. | Read it as intent. It is the input side of the causal claim, and it says nothing about outcome. | It is not evidence that any article met it, and it is not a prediction. |
| simulated | /wwd/examples/simulated-strip.wwd | The value one run of one model returned, with the solver and its version named. | Read it as a statement about the model. Its weight rests on the model envelope, the run envelope and the convergence status. | It cannot answer an acceptance criterion, and it cannot be compared to a measurement without keeping both original values and identifying the comparison activity. |
| measured | /wwd/examples/muscle-strip-asbuilt.wwd | The value an assay read on realization lot/WW-2026-0142. | Read it as evidence about that realization at that design revision, in the unit its criterion names and as the statistic its criterion constrains. | It does not transfer to another lot or another revision, and a recorded pass is a claim, not evidence: a consumer recomputes the verdict from the value, the comparator and the limit. |
How the causal projection reads an as-built package
do(controls), context, responses, yield.
Because controls are declared as interventions, a conforming as-built package is
losslessly projectable to the tuple (do(controls), context, responses, yield),
where do denotes the interventional operator of Pearl causal calculus. The
reference implementation is validator/wwd/causal.py. A design-only package
projects to nothing, and a package carrying only simulation content projects to nothing,
because neither carries an observation.
| Slot | Source | Contents |
|---|---|---|
| do(controls) | design.json | Fields with causal role control, carrying the value as designed. Provenance designed. |
| actual controls | results.json | Measured results whose causal role is control. The process log, held apart from the intended value. |
| context | design.json and results.json | Fields with causal role context, plus every entry of the results context block. wwd:donor_id, wwd:passage_number in muscle-strip-asbuilt.wwd. |
| responses | results.json | Measured results whose causal role is response, keyed by measurand quantity and, where the statistic is not a location statistic, by quantity and statistic together. |
| targets | design.json | Fields with causal role response. The value the tissue was asked to reach. |
| yield | results.json | units_meeting over units_tested, with the criterion it summarises: 12 of 12 against AC-001. |
The designed control and the measured control occupy separate slots. ECM stiffness enters as
12 kPa under do(controls) and as 12.4 kPa under the process log, so the gap
between them reads as a process deviation rather than as biological variability. Simulation
results enter no slot.
Which package carries which classes
The seven example packages.
| Package | designed | simulated | measured | realization | Reading |
|---|---|---|---|---|---|
| muscle-strip-designed.wwd | yes | no | no | no | As-designed. Design document only, no results document. |
| graded-strip.wwd | yes | no | no | no | As-designed. A graded stiffness field and its criteria, nothing built. |
| bioprinted-strip.wwd | yes | no | no | no | As-designed, with delegated 3MF geometry. |
| muscle-strip-asbuilt.wwd | yes | no | yes | yes | As-built. 4 measured results against one realization. |
| muscle-strip-highstiff.wwd | yes | no | yes | yes | As-built at a second stiffness setting, giving a two-point design. |
| neurontile-asbuilt.wwd | yes | no | yes | yes | As-built. 5 measured results, yield 7 of 8. |
| simulated-strip.wwd | yes | yes | yes | yes | All three classes in one package: designed fields, a model and run with two simulation results, and measured results against a realization. |
Every package carries designed content, because the design document is the root of a WWD package. graded-strip.wwd carries 4 acceptance criteria and no results document, so it is as-designed. simulated-strip.wwd is the only example carrying all three classes, and it keeps them in three separate collections of one results document.
Questions
What are the Core provenance classes?
designed, simulated, measured, inferred and assumed. Every field, state value, model input, model output, acceptance criterion target and result MUST declare one, and a provenance class is not a confidence score. Measured content MUST identify an assay or observation activity. Simulated content MUST identify a model run. Inferred content MUST identify source entities and inference activity. Assumed content SHOULD state rationale. Designed content SHOULD identify authoring agent and revision. A scientific assertion with no provenance is reported as F09_NO_PROVENANCE.
What links an as-built package back to its design?
The realization. Every realization MUST have an identifier and MUST reference the exact component design revision realized, and it MUST declare which identifier scheme its identifier belongs to. In muscle-strip-asbuilt.wwd the realization is lot/WW-2026-0142, scheme local, design revision 1.3.0, and the design document carried in the same package is at that revision. A realization with no identifier is R05_NO_REALIZATION, with no scheme is R05_NO_ID_SCHEME, and with no design revision is R05_NO_DESIGN_REVISION.
How does a package become as-built?
By carrying measured results. A WWD package with no measured results is as-designed. A package with one or more measured results is as-built in addition to carrying its unchanged design. Mode MUST be derived as as_built := measured_results is nonempty, and a package MUST NOT contain a manually authored mode flag; a stored flag is reported as R06_AUTHORED_MODE_FLAG. Appending measured results MUST NOT mutate acceptance criteria.
Where does a simulated study live when nothing has been built?
Section 18.5 places the model and run envelopes in the design document for a design-only study, because a design-only package has no results document to put them in, and beside the simulation results in the results document for a package that reports outputs. A package with no realization MAY carry a results document holding only simulation content: simulation_results, plus the simulation_models and simulation_runs that produced them. Such a document MUST NOT declare a realization and MUST NOT carry measured results, and its manifest role is simulation_result rather than measured_result_data. The same identifier MUST NOT appear in both places, reported as Q09_ENVELOPE_DUPLICATED.
Can a simulated value be relabelled as measured?
No. A simulated output MUST have simulated provenance and reference exactly one run, and a measured output MUST have measured provenance and reference an observation activity. A result MUST NOT copy a simulated value into the measured-results collection. The reference validator reports a row in measured_results carrying provenance simulated as F09_SIMULATED_AS_MEASURED and stops processing that row, and a row carrying any provenance other than measured as F09_BAD_RESULT_PROVENANCE. The test suite carries the vector invalid-simulated-as-measured against section 18.1.
Can a simulation result be compared with a criterion?
A simulation result MAY be compared with a designed requirement, and such a comparison is a simulation assessment rather than an acceptance result. A simulation result MUST NOT satisfy a measured acceptance criterion unless that criterion explicitly permits simulation, in which case it is a design verification criterion rather than a lot acceptance criterion. A comparison between simulation and measurement MUST keep both original values and identify the comparison activity.
What does a draft package do with a realization?
It carries none. A draft package MUST NOT declare a realization or carry measured results, and a draft carrying either is reported as W02_DRAFT_WITH_RESULTS. A draft MAY violate the design-layer obligations of sections 5 to 18, a consumer MUST still report every violation with the same code and severity, and a draft MUST NOT be reported as reaching any conformance class.
Which conformance class covers an as-built package?
WWD-As-Built. A WWD-As-Built package MUST satisfy WWD-Design-Core and sections 15 to 17, every measured result MUST resolve to a criterion and realization, every measured assertion MUST map to an observation activity, the package MUST preserve designed and measured values separately, and a consumer MUST derive rather than trust as-built mode and disposition. Simulation content is covered by WWD-Simulation, under which a consumer MUST NOT present simulated results as acceptance measurements.
Continue
Related pages.
- Causal roles. control, response, context and derived, and the second axis every assertion carries.
- Acceptance criteria. Statistical acceptance, named assays, recomputed verdicts, disposition and yield.
- The WWD file format. Container, manifest, design and results documents.
- Property fields. Scalar-or-field slots and the five Core backings.
- Seven example packages, each read field by field.
- The reference validator. Every diagnostic code and how to run it.
- The WWD 0.1 draft specification. All normative sections with anchors.