Study Contract technical reference
A machine-readable Study Contract: field guide and example schema
A method-neutral technical reference for expressing one outsourced cell-study plan as versioned JSON with explicit intent, biology, measurement, evidence, roles, changes, unknowns and review boundaries.
SingularCell Research. Reviewed for official-source coverage, schema mechanics and scientific boundaries. The reference documents a structure and does not prescribe biology, methods, thresholds or acceptance decisions.
How to use this resource
Use the field map and synthetic examples to design one bounded research-use contract profile. Do not paste confidential data here, and route scientific, operational, security, legal and release decisions to accountable people.
Entries stay in this browser page and are not submitted to SingularCell. Download or storage is not implied.
Minimum Study Contract field groups
Use these groups to make one plan reviewable without treating field presence as proof that the proposed science or execution is adequate.
Keep six validation status families separate
A single valid flag hides distinct questions. Report each family independently and preserve review-required states.
| Status family | May report | Must not imply |
|---|---|---|
| schema_status | Syntax, types and encoded schema assertions passed, failed or were indeterminate | Truth, completeness or scientific validity |
| reference_status | IDs, pinned versions and declared hashes resolved or failed deterministic checks | Correct real-world identity, authority or suitability |
| provenance_status | Required nodes and relations are present and selected signatures or hashes were checked | Truth, authorship, custody or complete history |
| plan_completeness_status | Configured fields and evidence states are populated | Adequate design or readiness to execute |
| execution_conformance_status | Recorded execution matches or differs from exact encoded plan fields | Truthful execution, valid methods or immaterial deviations |
| scientific_review_status | A human review assertion exists for an exact scope and version | Scientific truth or acceptance beyond that scope |
Represent missing evidence honestly
Use explicit states instead of blank fields, silent defaults or invented values that make a contract appear more complete than the evidence supports.
| State | Exact meaning | Required next record |
|---|---|---|
| NOT_PROVIDED | The expected item was not supplied | Reason, owner, impact and review requirement |
| NOT_REQUESTED | The item was not requested for this version | Scope rationale and reviewer |
| REQUESTED_PENDING | A request exists but the item has not arrived | Owner, request time and due or escalation state |
| UNAVAILABLE | The item cannot be supplied under the stated conditions | Source explanation, impact and decision owner |
| NOT_APPLICABLE_WITH_REASON | A named reviewer says the item does not apply | Exact rationale, scope and reviewer record |
| UNKNOWN | The responsible party cannot determine the value | Owner, impact and review or escalation path |
| CONFLICTING | Two or more supplied assertions disagree | All versions, conflict owner and resolution record |
Synthetic Study Contract instance
This deliberately incomplete JSON object shows how intent, material, measurement, criteria, roles and missing evidence can remain explicit before execution.
{
"$schema": "https://singularcell.com/schemas/study-contract/0.1/schema.json",
"schema_version": "0.1.0",
"contract_id": "sc:study:synthetic-demo",
"contract_version_id": "sc:study:synthetic-demo:v1",
"version_number": 1,
"status": "DRAFT",
"title": "Synthetic reporter study — demonstration",
"intended_decisions": [{
"decision_id": "decision:1",
"intended_use": "software demonstration only",
"excluded_uses": ["clinical release", "patient care"],
"scientific_judgment_required": true
}],
"biological_materials": [{
"material_id": "material:synthetic-cell-model",
"declared_identity": "Synthetic example cell model",
"authentication_status": "AUTHENTICATION_PLANNED"
}],
"measurements": [{
"measurement_id": "measurement:reporter-24h",
"measurand_definition": "Declared reporter-associated signal",
"readout_definition": "Instrument response in declared arbitrary units",
"timepoint": {"value": 24, "unit": "hour", "reference_event": "treatment_start"}
}],
"criteria": [{
"criterion_id": "criterion:demo-signal",
"role": "INFORMATIONAL",
"timing": "PROSPECTIVE",
"maturity_status": "SYNTHETIC",
"automatic_decision_permitted": false
}],
"limitations": ["Scientific validation has not been established for any criterion in this fixture."],
"missing_evidence": [{
"missing_item_id": "missing:instrument-config",
"object_path": "/method_implementations/0/instrument_configuration",
"state": "NOT_PROVIDED",
"reason": "No laboratory declaration has been supplied.",
"review_required": true
}]
}Boundary: This synthetic object demonstrates information structure only. It is incomplete, non-prescriptive and does not establish scientific validity, execution readiness, capability, compliance or approval.
Conservative Draft 2020-12 schema outline
This abbreviated schema demonstrates explicit dialect, stable identity, required field groups, controlled states, conditional presence and closed properties.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://singularcell.com/schemas/study-contract/0.1/schema.json",
"title": "SingularCell Study Contract",
"description": "Structural research-use schema. Passing validation does not establish truth, scientific validity, compliance, suitability, equivalence, custody, approval authenticity or execution.",
"type": "object",
"required": [
"schema_version", "contract_id", "contract_version_id",
"version_number", "status", "title", "intended_decisions",
"biological_materials", "measurements", "criteria",
"roles", "expected_data", "limitations", "missing_evidence"
],
"properties": {
"$schema": {"const": "https://singularcell.com/schemas/study-contract/0.1/schema.json"},
"schema_version": {"const": "0.1.0"},
"contract_id": {"$ref": "#/$defs/stableId"},
"contract_version_id": {"$ref": "#/$defs/stableId"},
"version_number": {"type": "integer", "minimum": 1},
"status": {"enum": ["DRAFT", "IN_REVIEW", "APPROVED_FOR_HANDOFF", "SUPERSEDED", "WITHDRAWN"]},
"title": {"type": "string", "minLength": 1},
"intended_decisions": {"type": "array", "minItems": 1},
"biological_materials": {"type": "array", "minItems": 1},
"measurements": {"type": "array", "minItems": 1},
"criteria": {"type": "array"},
"roles": {"type": "array", "minItems": 1},
"expected_data": {"type": "array"},
"limitations": {"type": "array", "items": {"type": "string"}},
"missing_evidence": {"type": "array"}
},
"allOf": [{
"if": {"properties": {"status": {"const": "SUPERSEDED"}}, "required": ["status"]},
"then": {"required": ["supersedes_version_id"]}
}],
"unevaluatedProperties": false,
"$defs": {
"stableId": {"type": "string", "minLength": 1, "pattern": "^[A-Za-z][A-Za-z0-9._:/-]*$"}
}
}Boundary: This outline tests only the constraints it implements. Production use still requires pinned schema resources, validator configuration, application-level integrity checks and accountable scientific review.
A Study Contract makes requested work and missing evidence structurally inspectable before execution. Passing its schema proves only structural conformance under the recorded validator—not scientific validity or readiness.
Specify the plan before execution
A Study Contract is a versioned technical specification of requested work, not a legal contract or proof that the study design is sound. It should bind one exact plan version to the intended decision, material and cell context, measurements, methods, controls, replication, criteria, sites, roles, handoffs, expected evidence and review boundaries.
Every child object needs a stable identifier and explicit state. Amendments create a successor plan version; execution-time deviations and result-time corrections remain separate records that point back to the version they affect.
- Separate schema version from study-contract version
- Bind intended use and excluded uses to accountable roles
- Version material, method, instrument and software declarations
- Keep criteria, sources, timing and approval scope together
- Preserve amendments, deviations and corrections separately
Make missing evidence first-class
A machine-readable contract should not force invented certainty merely to pass validation. Important unknowns can carry an explicit state, reason, responsible party, decision impact and review requirement instead of disappearing as blank properties or being filled by defaults.
Biological identity, measurement meaning and criteria require context. Equal assay names, cell labels, units, instruments or schema-valid fields do not establish equal measurands, implementations, biological states or scientific suitability.
- Distinguish not provided, pending, unavailable and unknown
- Require a reason and accountable follow-up owner
- Preserve conflicts without selecting an automatic winner
- Separate authentication plans from linked evidence
- Never fabricate biological or approval content with defaults
Report validation with precise meaning
JSON Schema can check JSON types, required properties, enumerated states, local cardinality, patterns and encoded conditional presence rules. Cross-document identity resolution, version-chain integrity, applicability, authentication, authorization and scientific reasoning require other deterministic checks or accountable human review.
The safe success label is structurally valid against schema version X under validator Y. It must never collapse into scientifically valid, compliant, equivalent, ready to execute or accepted.
- Record schema ID, dialect, hash and validator configuration
- Record whether format keywords are asserted or annotated
- Return complete instance and schema paths for every error
- Keep structural, reference and provenance statuses separate
- Require human review for design, suitability and release
Primary sources
- JSON Schema Core — Draft 2020-12 ↗JSON Schema project · JSON data-model, dialect, schema-resource identity, references, applicators, unevaluated locations and validation output mechanics.
- JSON Schema Validation — Draft 2020-12 ↗JSON Schema project · Structural assertions, required properties, validation terminology, annotations and format-behavior boundaries.
- W3C — PROV Data Model ↗World Wide Web Consortium · Entities, activities, agents, plans, use, generation, derivation, revision, attribution, association and invalidation assertions.
- NIST — Research Data Framework, Version 2.0 ↗National Institute of Standards and Technology · Research lifecycle, machine-readable planning, data, metadata, standards, tools, roles, security, versions, retention and provenance.
- OECD — Principles and guidance for GLP compliance monitoring ↗Organisation for Economic Co-operation and Development · A bounded GLP-context example covering study identity, purpose, parties, sites, dates, methods, design, records, amendments, deviations, reporting and retention.
- NIH — Authentication of Key Biological and Chemical Resources ↗National Institutes of Health · Within NIH application scope, authentication planning for key resources such as cell lines is distinct from authentication data.
- NIH — Writing a Data Management and Sharing Plan ↗National Institutes of Health · Within NIH-funded scope, planning addresses data types, repositories, access, privacy, rights, sharing limitations and revisions.
- NIST — Building Measurement Confidence for Cell Characterization ↗National Institute of Standards and Technology · Cell-measurement complexity and the need to preserve measurement-assurance and uncertainty context.
- NIST — Measurement Uncertainty ↗National Institute of Standards and Technology · Measurement, measurand, reference, instrument, calibration and uncertainty concepts.
- JCGM/BIPM — International Vocabulary of Metrology ↗Joint Committee for Guides in Metrology / Bureau International des Poids et Mesures · Measurand, procedure, result, uncertainty, calibration, traceability, verification and intended-use validation vocabulary.
Limitations
- This is a research-use planning reference, not a legal agreement, protocol prescription, universal assay ontology or regulated electronic-record system.
- Schema validity proves only satisfaction of implemented assertions under the identified schema, validator and configuration.
- Complete fields do not prove true declarations, adequate study design, biological identity, method validity, laboratory capability or readiness to execute.
- Provenance links, hashes and recorded signatures do not by themselves prove origin, authorship, custody, authenticity, correctness or scientific validity.
- OECD, NIH, NIST, W3C, JSON Schema and JCGM/BIPM concepts remain bounded to their stated technical, policy, regulated or metrology contexts.
- Only accountable qualified people can decide design suitability, criteria, deviations, interpretation, acceptance, legal obligations and release.
- The public examples are synthetic and incomplete and must not receive confidential, personal, patient, proprietary or controlled study information.