Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:03:23Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:33, 6 July 2026
Line 277:		Line 277:
	* '''Read payload''' (<code>SpecimenDefinitionReadSpec</code>): adds <code>id</code> (= <code>external_id</code>), <code>version</code>, the qualified <code>slug</code>, and <code>slug_config</code>.		* '''Read payload''' (<code>SpecimenDefinitionReadSpec</code>): adds <code>id</code> (= <code>external_id</code>), <code>version</code>, the qualified <code>slug</code>, and <code>slug_config</code>.
	* The model maps to the FHIR <code>SpecimenDefinition</code> resource. Care's spec is intentionally minimal: one container per definition, and behaviour changes bump <code>version</code> rather than mutate published records.		* The model maps to the FHIR <code>SpecimenDefinition</code> resource. Care's spec is intentionally minimal: one container per definition, and behaviour changes bump <code>version</code> rather than mutate published records.

			{{Navbox definitions}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:44:53Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Specimen Definition
|order=5
|introduced=3.0
|model=SpecimenDefinition
|reference=References/Value Set
}}

A <code>SpecimenDefinition</code> 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 [[References/Activity Definition]] or [[References/Service Request]] references one so the same container and handling rules apply every time. When a concrete [[References/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: <code>type_collected</code>, <code>patient_preparation</code>, <code>collection</code>, and <code>type_tested</code> are opaque <code>JSONField</code>s. Their real structure — the enums, value-set bindings, and read/write API schemas — lives in the Pydantic resource specs documented below.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/specimen_definition.py <code>care/emr/models/specimen_definition.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/specimen_definition/spec.py <code>care/emr/resources/specimen_definition/spec.py</code>]
* Value sets: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/specimen_definition/valueset.py <code>care/emr/resources/specimen_definition/valueset.py</code>]
* Conversion helper: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/specimen_definition/specimen.py <code>care/emr/resources/specimen_definition/specimen.py</code>]
* ViewSet: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/specimen_definition.py <code>care/emr/api/viewsets/specimen_definition.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>SpecimenDefinition</code>
| Reusable definition of a kind of specimen: what to collect, how to prepare the patient, how to collect it, and how it is contained and tested
|}

<code>SpecimenDefinition</code> extends [[References/Base models & conventions|<code>SlugBaseModel</code>]]: the Care EMR base with <code>FACILITY_SCOPED = True</code>, a facility-scoped <code>slug</code>, <code>external_id</code>, <code>history</code>/<code>meta</code> JSON, audit fields, and soft-delete semantics.

== <code>SpecimenDefinition</code> fields ==

=== Identity & status ===

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=SpecimenDefinition|section=Identity & status|name=facility|type=FK → facility.Facility (PROTECT)|notes=model: optional}}
{{Field|model=SpecimenDefinition|section=Identity & status|name=version|type=IntegerField|notes=default <code>1</code>}}
{{Field|model=SpecimenDefinition|section=Identity & status|name=slug|type=CharField(255)|notes=yes (server-built)}}
{{Field|model=SpecimenDefinition|section=Identity & status|name=title|type=CharField(1024)|notes=yes}}
{{Field|model=SpecimenDefinition|section=Identity & status|name=derived_from_uri|type=TextField|notes=optional}}
{{Field|model=SpecimenDefinition|section=Identity & status|name=status|type=CharField(255)|notes=yes}}
{{Field|model=SpecimenDefinition|section=Identity & status|name=description|type=TextField|notes=yes}}
|}

=== Collection & testing detail (JSON fields) ===

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

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Notes
|-
| <code>type_collected</code>
| <code>JSONField</code> (<code>null=True</code>)
| <code>Coding</code> bound to '''Specimen Type Code''' value set
| Required on write. The kind of material collected. See [[#bound-value-sets
|-
| <code>patient_preparation</code>
| <code>JSONField</code> (<code>default=list</code>)
| <code>list[Coding]</code> bound to '''Prepare Patient Prior Specimen Code''' value set
| Defaults to <code>[]</code>. Steps the patient follows before collection
|-
| <code>collection</code>
| <code>JSONField</code> (<code>null=True</code>)
| <code>Coding</code> bound to '''Specimen Collection Code''' value set, optional
| The specimen collection procedure
|-
| <code>type_tested</code>
| <code>JSONField</code> (<code>default=dict</code>)
| <code>TypeTestedSpec</code> (nested), optional
| Container, handling, and testing detail. See [[#typetestedspec
|}

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

{| class="wikitable"
|-
! Type
! Where
! Shape
|-
| <code>Coding</code>
| [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/coding.py <code>resources/common/coding.py</code>]
| <code>{ system: str?, version: str?, code: str (required), display: str? }</code>, <code>extra="forbid"</code>
|-
| <code>QuantitySpec</code>
| spec.py
| <code>{ value: Decimal (max_digits=20, decimal_places=0), unit: Coding }</code> — <code>decimal_places=0</code>, so integer-valued
|-
| <code>MinimumVolumeSpec</code>
| spec.py
| <code>{ quantity: QuantitySpec?, string: str? }</code>; a validator forbids supplying both
|-
| <code>ContainerSpec</code>
| spec.py
| <code>{ description: str?, capacity: QuantitySpec?, minimum_volume: MinimumVolumeSpec?, cap: Coding? (bound to Container Cap), preparation: str? }</code>
|-
| <code>DurationSpec</code>
| spec.py
| <code>{ value: Decimal (max_digits=20, decimal_places=0), unit: Coding }</code> — <code>unit</code> not yet restricted to datetime units
|-
| <code>RangeSpec</code>
| spec.py
| <code>{ low: QuantitySpec?, high: QuantitySpec? }</code>
|-
| <code>HandlingSpec</code>
| spec.py
| <code>{ temperature_qualifier: HandlingConditionOptions?, temperature_range: RangeSpec?, max_duration: DurationSpec?, instruction: str? }</code>
|-
| <code>TypeTestedSpec</code>
| spec.py
| see [[#typetestedspec
|}

=== <code>TypeTestedSpec</code> ===

The structured shape of the <code>type_tested</code> JSON field. A definition holds a single container; for multiple containers per test, repeat the definition in the [[References/Activity Definition]] spec.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=is_derived|type=bool|notes=yes}}
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=preference|type=PreferenceOptions|notes=yes}}
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=container|type=ContainerSpec|notes=optional}}
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=requirement|type=str|notes=optional}}
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=retention_time|type=DurationSpec|notes=optional}}
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=single_use|type=bool|notes=optional}}
{{Field|model=SpecimenDefinition|section=TypeTestedSpec|name=handling|type=HandlingSpec|notes=optional}}
|}

== Enums ==

=== <code>SpecimenDefinitionStatusOptions</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Being authored, not yet in use
|-
| <code>active</code>
| In use
|-
| <code>retired</code>
| Withdrawn from use
|}

=== <code>PreferenceOptions</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>preferred</code>
| Preferred specimen for the test
|-
| <code>alternate</code>
| Acceptable alternative specimen
|}

=== <code>HandlingConditionOptions</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>room</code>
| Room temperature
|-
| <code>refrigerated</code>
| Refrigerated
|-
| <code>frozen</code>
| Frozen
|}

== Resource specs (API schema) ==

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

{| class="wikitable"
|-
! Spec class
! Role
! Fields / behaviour
|-
| <code>BaseSpecimenDefinitionSpec</code>
| shared base
| <code>id</code>, <code>title</code>, <code>derived_from_uri</code>, <code>status</code>, <code>description</code>, <code>type_collected</code>, <code>patient_preparation</code>, <code>collection</code>, <code>type_tested</code>. Holds the coded-field value-set bindings and the nested <code>type_tested</code> shape
|-
| <code>SpecimenDefinitionWriteSpec</code>
| write · create & update
| Base fields '''plus''' <code>slug_value: SlugType</code>. <code>perform_extra_deserialization</code> copies <code>slug_value</code> → <code>obj.slug</code> (the ViewSet then fully-qualifies it). <code>facility</code>, <code>version</code>, and the stored <code>slug</code> are never client-supplied
|-
| <code>SpecimenDefinitionReadSpec</code>
| read · list & detail
| Base fields '''plus''' <code>version: int?</code>, <code>slug: str</code>, <code>slug_config: dict</code>. <code>perform_extra_serialization</code> sets <code>id = obj.external_id</code> and <code>slug_config = obj.parse_slug(obj.slug)</code>, decomposing the qualified slug into <code>{ facility, slug_value }</code>
|}

Nested specs used by the schemas: <code>TypeTestedSpec</code>, <code>ContainerSpec</code>, <code>MinimumVolumeSpec</code>, <code>QuantitySpec</code>, <code>DurationSpec</code>, <code>RangeSpec</code>, <code>HandlingSpec</code> (see [[#related-models|Related models]]).

=== Validation rules ===

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

=== Bound value sets ===

{| class="wikitable"
|-
! Field
! Value set
! Slug
! Source system(s)
|-
| <code>type_collected</code>
| Specimen Type Code
| <code>system-specimen_type-code</code>
| HL7 v2-0487 (unbounded include)
|-
| <code>patient_preparation[*]</code>
| Prepare Patient Prior Specimen Code
| <code>system-prepare_patient_prior_specimen_code</code>
| SNOMED CT, <code>is-a 703763000</code>
|-
| <code>collection</code>
| Specimen Collection Code
| <code>system-specimen_collection_code</code>
| SNOMED CT (curated list: aspiration, biopsy, puncture, excision, scraping, clean-catch/timed/catheterized urine, coughed sputum, finger-prick)
|-
| <code>container.cap</code>
| Container Cap
| <code>system-container_cap-code</code>
| HL7 <code>container-cap</code> code system
|}

== Methods & save behaviour ==

<code>SpecimenDefinition</code> overrides no <code>save()</code>/<code>delete()</code> and defines no custom methods. Slug helpers, audit fields, and soft-delete come from [[References/Base models & conventions|<code>SlugBaseModel</code>]]. The side effects below live in the resource spec and the ViewSet, not the model:

* '''Slug qualification (write).''' Clients send a bare <code>slug_value</code>. <code>SpecimenDefinitionWriteSpec.perform_extra_deserialization</code> sets <code>obj.slug = slug_value</code>; then the ViewSet's <code>perform_create</code>/<code>perform_update</code> rewrites it via <code>SpecimenDefinition.calculate_slug_from_facility(facility.external_id, slug)</code> → <code>f-<facility_external_id>-<slug_value></code>.
* '''Facility binding (create).''' <code>perform_create</code> sets <code>instance.facility</code> from the <code>facility_external_id</code> URL kwarg before saving.
* '''Slug decomposition (read).''' <code>SpecimenDefinitionReadSpec.perform_extra_serialization</code> exposes <code>slug_config = obj.parse_slug(obj.slug)</code>, splitting the stored slug back into <code>{ facility, slug_value }</code>.
* '''Specimen instantiation.''' <code>convert_sd_to_specimen</code> ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/specimen_definition/specimen.py <code>specimen.py</code>]) builds a [[References/Specimen|<code>Specimen</code>]] from a definition with <code>status="available"</code>, <code>specimen_type = definition.type_collected</code>, and <code>specimen_definition = <definition></code>, 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 <code>lookup_field = "slug"</code>. Every operation requires <code>facility_external_id</code> in the URL.
* '''Authorization.''' Writes require <code>can_write_facility_specimen_definition</code>; list/retrieve require <code>can_list_facility_specimen_definition</code> on the facility — otherwise <code>403 PermissionDenied</code>. The queryset is filtered to the URL facility.
* '''Filtering / ordering.''' <code>status</code> (iexact) and <code>title</code> (icontains) filters; ordering by <code>created_date</code> / <code>modified_date</code>.
* '''Write payload''' (<code>SpecimenDefinitionWriteSpec</code>): send <code>slug_value</code>, <code>title</code>, <code>status</code>, <code>description</code>, the coded fields (<code>type_collected</code>, <code>patient_preparation</code>, <code>collection</code>) as <code>Coding</code> objects, and <code>type_tested</code>. Don't send <code>facility</code>, <code>version</code>, or the qualified <code>slug</code> — they're server-managed.
* '''Read payload''' (<code>SpecimenDefinitionReadSpec</code>): adds <code>id</code> (= <code>external_id</code>), <code>version</code>, the qualified <code>slug</code>, and <code>slug_config</code>.
* The model maps to the FHIR <code>SpecimenDefinition</code> resource. Care's spec is intentionally minimal: one container per definition, and behaviour changes bump <code>version</code> rather than mutate published records.

{{Related}}

References/Specimen Definition - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed