Laboratory & radiology

Specimen Definition

A SpecimenDefinition is a reusable, facility-scoped template for a kind of specimen: what material to collect, how to prepare the patient, how to collect it, and how it's held in a container for testing. A lab maintains a repository of these,…

3.1 · versioned documentation · 7 min read

A SpecimenDefinition is a reusable, facility-scoped template for a kind of specimen: what material to collect, how to prepare the patient, how to collect it, and how it's held in a container for testing. A lab maintains a repository of these, and an Activity Definition or Service Request references one so the same container and handling rules apply every time. When a concrete Specimen is instantiated from a definition, the link is kept and the specimen copies the definition's data for history and integrity.

The Django model is only the storage layer: type_collected, patient_preparation, collection, and type_tested are opaque JSONFields. Their real structure — the enums, value-set bindings, and read/write API schemas — lives in the Pydantic resource specs documented below.

Source:

• Model: care/emr/models/specimen_definition.py
• Resource spec: care/emr/resources/specimen_definition/spec.py
• Value sets: care/emr/resources/specimen_definition/valueset.py
• Conversion helper: care/emr/resources/specimen_definition/specimen.py
• ViewSet: care/emr/api/viewsets/specimen_definition.py

Models

SpecimenDefinition extends SlugBaseModel: the MANSOQ EMR base with FACILITY_SCOPED = True, a facility-scoped slug, external_id, history/meta JSON, audit fields, and soft-delete semantics.

SpecimenDefinition fields

Identity & status

Collection & testing detail (JSON fields)

The model stores these as raw JSON; the spec defines their true shape and value-set bindings.

Each bound coded field accepts a Coding object ({ system, version?, code, display? }); ValueSetBoundCoding validates the code against the bound value set at de-serialization time.

Related models

TypeTestedSpec

The structured shape of the type_tested JSON field. A definition holds a single container; for multiple containers per test, repeat the definition in the Activity Definition spec.

Enums

SpecimenDefinitionStatusOptions values

PreferenceOptions values

HandlingConditionOptions values

Resource specs (API schema)

All specs build on EMRResource (serialize/de_serialize, perform_extra_serialization/perform_extra_deserialization). __exclude__ = ["facility"] keeps facility out of both directions. The ViewSet wires pydantic_model = SpecimenDefinitionWriteSpec for create/update and pydantic_read_model = SpecimenDefinitionReadSpec for list/retrieve.

Nested specs used by the schemas: TypeTestedSpec, ContainerSpec, MinimumVolumeSpec, QuantitySpec, DurationSpec, RangeSpec, HandlingSpec (see Related models).

Validation rules

• slug_value (SlugType): string, length 5–50, matching ^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$ (URL-safe; starts and ends alphanumeric).
• Coded fields type_collected, patient_preparation[*], collection, and container.cap: ValueSetBoundCoding validates each Coding.code against its bound value set during de-serialization and rejects unknown codes.
• MinimumVolumeSpec: quantity and string are mutually exclusive — supplying both raises "Only one of quantity or string should be provided".
• QuantitySpec / DurationSpec value: Decimal, max_digits=20, decimal_places=0 (integer-valued).
• Slug uniqueness (ViewSet validate_data): the fully-qualified f-<facility>-<slug_value> must be unique within the facility (case-insensitive), else "Specimen Definition with this slug already exists." On update, the current record is excluded from the check.

Bound value sets

Methods & save behaviour

SpecimenDefinition overrides no save()/delete() and defines no custom methods. Slug helpers, audit fields, and soft-delete come from SlugBaseModel. The side effects below live in the resource spec and the ViewSet, not the model:

• Slug qualification (write). Clients send a bare slug_value. SpecimenDefinitionWriteSpec.perform_extra_deserialization sets obj.slug = slug_value; then the ViewSet's perform_create/perform_update rewrites it via SpecimenDefinition.calculate_slug_from_facility(facility.external_id, slug) → f-<facility_external_id>-<slug_value>.
• Facility binding (create). perform_create sets instance.facility from the facility_external_id URL kwarg before saving.
• Slug decomposition (read). SpecimenDefinitionReadSpec.perform_extra_serialization exposes slug_config = obj.parse_slug(obj.slug), splitting the stored slug back into { facility, slug_value }.
• Specimen instantiation. convert_sd_to_specimen (specimen.py) builds a Specimen from a definition with status="available", specimen_type = definition.type_collected, and specimen_definition = <definition>, preserving the link and a copy of the type.

API integration notes

• Endpoints are facility-scoped. The ViewSet supports create, retrieve, update, list, and upsert with lookup_field = "slug". Every operation requires facility_external_id in the URL.
• Authorization. Writes require can_write_facility_specimen_definition; list/retrieve require can_list_facility_specimen_definition on the facility — otherwise 403 PermissionDenied. The queryset is filtered to the URL facility.
• Filtering / ordering. status (iexact) and title (icontains) filters; ordering by created_date / modified_date.
• Write payload (SpecimenDefinitionWriteSpec): send slug_value, title, status, description, the coded fields (type_collected, patient_preparation, collection) as Coding objects, and type_tested. Don't send facility, version, or the qualified slug — they're server-managed.
• Read payload (SpecimenDefinitionReadSpec): adds id (= external_id), version, the qualified slug, and slug_config.
• The model maps to the FHIR SpecimenDefinition resource. MANSOQ's spec is intentionally minimal: one container per definition, and behaviour changes bump version rather than mutate published records.

Related

• Reference: Specimen
• Reference: Service Request
• Reference: Observation Definition
• Reference: Activity Definition
• Reference: Base model
• Reference: Valueset
• Source: model on GitHub · spec on GitHub · value sets on GitHub

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/definitions/specimen-definition.mdx:1 · f6e9f05f