A cryopreservation experiment produces records that must stay interpretable years later. A post-thaw viability figure means little without the cooling profile that preceded it, the cryoprotectant (CPA) formulation, the lot numbers of its components and the assay used to count cells. WIA-CRYO-010 therefore makes one rule absolute: all interchange data MUST be expressed as JSON-LD. Every other serialization in this chapter is a derived view of that canonical form.
Phase 1 of the specification defines three principal record types. Each carries its own @type, so a consumer can route a document without inspecting its body.
| @type | Describes | Notable content |
|---|---|---|
| CryoResearchExperiment | One study from proposal to archive | investigator, lifecycle, scientific and technical blocks, results, metadata |
| CryoprotectantFormulation | A reusable CPA recipe | permeating and non-permeating CPAs, osmolality, glass transition temperature, performance metrics |
| ViabilityAssessment | One measurement event on one sample | experiment reference, sample ID, assessment time, time post-thaw |
The context binds the standard's own vocabulary and borrows three external ones: schema.org, XML Schema datatypes and QUDT for units. Every document is wrapped in the same envelope of identity, version and timestamps.
{
"@context": "https://wia.org/standards/cryo-research/v1",
"@type": "CryoResearchData",
"@id": "urn:uuid:{UUID}",
"version": "1.0.0",
"created": "ISO-8601 timestamp",
"modified": "ISO-8601 timestamp",
"data": {}
}The experiment schema groups fields by who asks the question. The scientific block holds the hypothesis, subject type, species, sample size, replicates and control groups. The technical block holds the cooling and warming protocols, storage duration (an ISO-8601 duration), assessment methods and equipment. The results block separates a primary endpoint from secondary endpoints and links to raw data by URI. A trimmed excerpt:
{
"@type": "CryoResearchExperiment",
"experimentId": "string (UUID or unique identifier)",
"title": "string (required)",
"scientific": {
"researchType": "enum [CPA_OPTIMIZATION, COOLING_RATE, REVIVAL_PROTOCOL, ...]",
"subjectType": "enum [CELL_CULTURE, TISSUE, ORGAN, ORGANISM, GAMETE, EMBRYO]",
"replicates": "integer"
},
"results": { "rawDataLinks": "array of URIs" }
}The lifecycle.status field is an enumeration, which keeps repository queries and dashboards from drifting into free-text variants:
The API's DELETE operation is a soft delete that archives an experiment rather than erasing it. That matches the long retention horizon of this field.
People, institutions and literature are referenced through persistent identifiers rather than names: an ORCID in the 0000-0000-0000-0000 pattern for the principal investigator, a ROR identifier for the institution, DOIs for related publications and CAS numbers for chemical components. The SDK examples of the v2.0 release use a human-readable experiment ID of the form CRYO-YYYY-NNN, for example CRYO-2025-001. The Phase 1 schema accepts a UUID or any unique identifier. A pipeline should store both when both exist.
Spreadsheets remain the working tool of many cryobiology benches, so the protocol phase defines a CSV export per experiment (GET /experiments/{id}/export?format=csv). Two requirements are explicit: a header row is mandatory, and the encoding is UTF-8. CSVW (CSV on the Web) is the established W3C way to ship a small metadata file next to a CSV. It declares column datatypes, units and the mapping back to the JSON-LD vocabulary. The specification text names CSV only, so any CSVW sidecar is an implementation choice layered on top of that contract.
A temperature profile is naturally tabular: one row per sample point. The three fields below come from the SDK example, where a profile has a unit and a sampling rate and each data point pairs chamber and sample readings.
| time | temperature | sample_temperature |
|---|---|---|
| 0 | 37 | 37 |
| 60 | -80 | -79 |
| 120 | -196 | -196 |
The gap between chamber and sample columns is the scientifically interesting part, because the sample lags the chamber during cooling. A flattening step must never keep only one of the two columns. The profile-level unit and sampling_rate belong in the sidecar metadata, since a bare CSV loses them.
The core concept sheet requires at least 3 data points and recommends 60 or more for detailed profiles. Real controlled-rate freezers and multi-probe loggers can emit far more, and a flow cytometer exports FCS files that the integration phase references by name (rawDataFile). HDF5 is an established hierarchical container for numeric arrays with attached attributes, chunking and compression. It suits that bulk. The specification does not define an HDF5 profile, so the sensible pattern is to keep the array in HDF5 and cite it from the JSON-LD through results.rawDataLinks.
The mapping below is a suggestion that reuses field names from the standard. It is not a normative profile.
| HDF5 element | Content | Source field |
|---|---|---|
| Group per experiment | Attribute holding the experiment identifier | experimentId |
| Dataset: time | Elapsed time axis | time |
| Dataset: chamber | Chamber readings | temperature |
| Dataset: sample | Probe readings | sample_temperature |
| Dataset attributes | Unit and sampling interval | unit, sampling_rate |
Multi-center collaboration produces questions across experiments: which CPA combinations gave the highest post-thaw viability for hepatocytes, and how does that vary with cooling rate? Parquet is an established columnar format that answers such questions efficiently, because an engine reads only the viability and formulation columns it needs. The standard's own API offers cell_type and viability_min filters and a bulk export with gzip compression. A Parquet table is best treated as an analytics copy of those exports, regenerated from JSON-LD and never edited by hand. The Phase 4 database example reaches the same end by storing the full document as JSONB with indexes on @type and lifecycle.status.
| Concern | External anchor | Used by |
|---|---|---|
| Generic web semantics | schema.org | JSON-LD context |
| Datatypes | XML Schema | JSON-LD context |
| Quantities and units | QUDT | JSON-LD context |
| Researcher identity | ORCID | principalInvestigator.orcid |
| Organization identity | ROR | institution.ror |
| Chemical identity | CAS number | CPA components |
| Clinical exchange | FHIR Specimen, Procedure, Observation | clinical cryopreservation data |
The clinical extensions are described as HIPAA/GDPR-compliant, and the experiment record has an irbApproval field in its metadata block. When a record is mapped to FHIR, the specimen and the observation (a viability count, for instance) should travel without direct patient identifiers. Funding source, keywords and related DOIs stay in metadata.
The interactive simulator has five tabs. They cover formatting experimental data, calculating viability metrics, building research protocols, testing API integration and running compliance tests. For this chapter the first tab matters most. Enter a profile, a CPA list and two viability values, and inspect the JSON-LD that comes out. Then use the test tab to see how a deliberately broken record is rejected.
The SDK package is @wia/cryo-010. Its submitExperiment call returns an experiment ID and a validation result. A shortened experiment object from the v2.0 example:
const experiment: ExperimentData = {
standard: 'WIA-CRYO-010',
version: '2.0',
experiment: { id: 'CRYO-2025-001', type: 'cell',
title: 'Mesenchymal Stem Cell Cryopreservation' },
sample: { type: 'human_mesenchymal_stem_cells',
source: 'bone_marrow', quantity: 5000000, unit: 'cells' },
protocol: {
method: 'slow_freeze',
cryoprotectant: { components: [
{ name: 'DMSO', concentration: 10, unit: 'percent_v/v' },
{ name: 'FBS', concentration: 20, unit: 'percent_v/v' },
{ name: 'Culture_Medium', concentration: 70, unit: 'percent_v/v' }
] }
},
measurements: { pre_freeze_viability: 98.5, post_thaw_viability: 85.2 }
};The specification has passed through four releases: v1.0 (initial), v1.1 (enhanced statistics), v1.2 (clinical extensions) and v2.0 (current). The source material shows two shapes side by side. The SDK example uses nested snake_case keys such as experiment.id and the unit string percent_v/v. The Phase 1 JSON-LD schema uses camelCase keys such as experimentId and the unit string %v/v. An adapter that converts between them should be explicit and tested, and it should preserve the original value when a unit string has no counterpart.
A CPA formulation carries a semantic version string and a status of EXPERIMENTAL, VALIDATED or DEPRECATED. Experiments reference the formulation they used, so a deprecated recipe must stay resolvable: the old experiments still point at it. A change to a component concentration is a new version. A change to a lot number is a new experiment record, not a new formulation.
The eBook ships in English and Korean, and the platform's CSV contract mandates UTF-8, so Hangul titles, investigator names and notes survive round trips. JSON-LD is Unicode-native. Keep controlled-vocabulary values such as CELL_CULTURE in their English form and place Korean wording in display fields. Timestamps should carry an explicit offset so that records written in Korea Standard Time compare correctly with those from other centers.
Korean laboratories typically start from an existing LIMS or an in-house database. Phase 4 prescribes a field-mapping table feeding an adapter that outputs JSON-LD:
{
"lims.sample_id": "sampleId",
"lims.operator_name": "operator",
"lims.test_date": "assessmentTime"
}Dates are the usual trouble spot. A local date-only value must become a full ISO-8601 timestamp with a declared offset before it enters assessmentTime.
| Task | Preferred form | Reason |
|---|---|---|
Submission to the API (application/ld+json) | JSON-LD | Mandatory canonical form |
| Bench review and spreadsheet analysis | CSV with header row, UTF-8 | Defined export contract |
| Dense multi-probe traces | HDF5, linked by URI | Array storage with attributes |
| Cross-experiment statistics | Parquet copy | Column scans over many records |
| Large imports | NDJSON (application/x-ndjson) | One experiment per line, streamable |
All submissions are checked against JSON Schema, and validation failures return 422. The error body has a code, a message and details:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Required field 'principalInvestigator' missing",
"details": {...}
}
}Beyond structural checks, the concept sheet adds domain rules. Cryoprotectant components must sum to 100%, and a temperature profile needs at least three data points.
A serialization pipeline should be tested with a small fixed corpus:
The two cases below are constructed illustrations of failure modes the schema is designed to catch, not reports of real incidents.
A lab transcribes a freezing medium as 10% DMSO, 20% FBS and 80% culture medium. The total is 110%. Each value looks plausible on its own, but the 100% rule rejects the whole composition with a 422. The root cause is usually a recipe copied from a version that used a different FBS fraction. Storing the formulation as a versioned record (section 3.17) makes the mismatch visible.
An analysis script reads %v/v from Phase 1 records and percent_v/v from SDK-origin records. A naive string comparison treats them as different units, so a cohort query silently drops half the data. The fix is a normalization table at the adapter boundary, with unknown strings rejected rather than guessed.
Automated reporting needs two things: a way to pull bulk data and a way to be told when it is ready. The bulk export accepts a list of experiment IDs, a format such as json-ld and a compression choice such as gzip, and it returns a job ID for asynchronous processing. Webhooks announce events such as experiment.completed and viability.low_alert, and each delivery carries an HMAC signature in the X-WIA-Signature header. The report generator should verify that signature before it serializes anything from the payload.
{
"event": "experiment.completed",
"experimentId": "exp-2025-001",
"timestamp": "2025-01-21T15:30:00Z",
"data": {...}
}Viability is a ladder rather than a single number: membrane integrity (trypan blue) at Level 1, metabolic activity (MTT or ATP) at Level 2, and further levels beyond. A serialized result should therefore name its assay. The formulation's performanceMetrics.cellViability carries a mean, an SD, n and the assay. The Phase 2 formulas show why: a 95% interval depends on sample size, so a mean without n cannot be re-analyzed. The Vitrification Quality Index (VQI) combines viability, metabolic activity and functional score, minus ice-crystal and apoptosis terms, with default weights 0.4, 0.3, 0.2, 0.05 and 0.05, scaled to 0–10. Store the weights alongside any VQI that departs from the defaults. Physical properties follow the same discipline. Osmolality is given in mOsm/kg, glass transition temperature in °C, and every number needs its unit field.
Consider a hospital laboratory that logs stem-cell freezing runs in a local LIMS with Korean free-text notes, and a university group that wants to pool the runs for an analysis. The workflow that fits the standard looks like this:
rawDataLinks.Canonical JSON-LD carries the meaning: identity, lifecycle, formulation, assessments and units. CSV, HDF5 and Parquet serve people and analytics engines without changing that meaning. The recurring risks are all about drift: units spelled two ways, compositions that do not sum, timestamps without offsets and lost sample-versus-chamber columns. The validation rules and the versioned formulation records exist to stop that drift early. The next chapter turns from the shape of the records to the numbers inside them, with the viability formulas, confidence intervals and quality indices that Phase 2 defines, and how to compute them reproducibly from the data structures described here.