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

2026-07-06T04:05:10Z

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

← Older revision		Revision as of 09:35, 6 July 2026
Line 373:		Line 373:
	specimen_definition → FK SpecimenDefinition (CASCADE, nullable)</syntaxhighlight>		specimen_definition → FK SpecimenDefinition (CASCADE, nullable)</syntaxhighlight>
	A <code>Specimen</code> is created to fulfill a [[References/Service Request\|<code>ServiceRequest</code>]] (a lab order) and may be shaped by a [[References/Specimen Definition\|<code>SpecimenDefinition</code>]] describing the expected sample. Results derived from a specimen surface through a [[References/Diagnostic Report\|<code>DiagnosticReport</code>]].		A <code>Specimen</code> is created to fulfill a [[References/Service Request\|<code>ServiceRequest</code>]] (a lab order) and may be shaped by a [[References/Specimen Definition\|<code>SpecimenDefinition</code>]] describing the expected sample. Results derived from a specimen surface through a [[References/Diagnostic Report\|<code>DiagnosticReport</code>]].

			{{Navbox clinical}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:44:34Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Specimen
|order=10
|introduced=3.0
|fhir=Specimen
|model=Specimen
|reference=References/Base models & conventions
}}

A <code>Specimen</code> is a physical sample — blood, tissue, swab — collected from a patient for laboratory analysis. You create one to fulfill a lab order, then update it as the specimen moves through collection, receipt, and processing.

Several of the model's fields (<code>care/emr/models/specimen.py</code>) are opaque <code>JSONField</code>s whose structure lives only in the Pydantic resource specs (<code>care/emr/resources/specimen/</code>). The specs define the enums, nested JSON shapes, value-set bindings, validation, and the read/write schemas, so you need both layers to work with this resource.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/specimen.py <code>care/emr/models/specimen.py</code>]
* Resource specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/specimen/spec.py <code>care/emr/resources/specimen/spec.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/specimen/valueset.py <code>valueset.py</code>]
* Viewset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/api/viewsets/specimen.py <code>care/emr/api/viewsets/specimen.py</code>]

== Models ==

<code>Specimen</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base providing <code>external_id</code>, audit fields, soft-delete via <code>deleted</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>Specimen</code> fields ==

=== Identity & status ===

{| class="wikitable"
|-
! Field
! Model type
! Spec shape / values
! Notes
|-
| <code>accession_identifier</code>
| <code>CharField(255)</code>, <code>db_index=True</code>
| <code>str</code>, default <code>""</code>
| Lab accession/barcode identifier; indexed for lookup. Defaults to <code>""</code>, so it's optional on write.
|-
| <code>status</code>
| <code>CharField(20)</code>
| <code>SpecimenStatusOptions</code> enum
| Required on base/create, optional on update. See [[#specimenstatusoptions-values
|-
| <code>specimen_type</code>
| <code>JSONField</code>
| <code>Coding</code> bound to value set <code>system-specimen_type-code</code>
| Kind of material collected, as a single coding. Required on base/create, optional on update.
|}

=== Clinical links ===

{| class="wikitable"
|-
! Field
! Model type
! Notes
|-
| <code>facility</code>
| <code>FK → Facility</code>
| <code>PROTECT</code>, nullable; the facility the specimen belongs to. Excluded from all specs (<code>__exclude__</code>).
|-
| <code>patient</code>
| <code>FK → Patient</code>
| <code>CASCADE</code>; the patient the specimen was collected from. Set on create via <code>subject_patient</code> (UUID).
|-
| <code>encounter</code>
| <code>FK → Encounter</code>
| <code>CASCADE</code>, nullable; the encounter during which collection occurred. Set on create via <code>subject_encounter</code> (UUID).
|-
| <code>service_request</code>
| <code>FK → ServiceRequest</code>
| <code>CASCADE</code>, nullable; the order this specimen fulfills. Set on create via <code>request</code> (UUID); excluded from base/read field copy.
|-
| <code>specimen_definition</code>
| <code>FK → SpecimenDefinition</code>
| <code>CASCADE</code>, nullable; the definition/template this specimen was derived from.
|}

=== Collection & processing ===

{| class="wikitable"
|-
! Field
! Model type
! Spec shape
! Notes
|-
| <code>collection</code>
| <code>JSONField</code> <code>default=dict</code>
| <code>CollectionSpec | None</code>, default <code>None</code>
| A single collection event: collector, method, body site, quantity, fasting. See [[#collectionspec
|-
| <code>received_time</code>
| <code>DateTimeField</code>, nullable
| <code>str | None</code>, default <code>None</code>
| When the lab received the specimen; ISO 8601 string in the spec.
|-
| <code>condition</code>
| <code>JSONField</code> <code>default=list</code>
| <code>list[Coding]</code> bound to <code>system-specimen-condition-code</code>, default <code>[]</code>
| Coded conditions/state of the specimen on receipt.
|-
| <code>processing</code>
| <code>JSONField</code> <code>default=list</code>
| <code>list[ProcessingSpec]</code>, default <code>[]</code>
| Processing steps applied. See [[#processingspec
|-
| <code>note</code>
| <code>TextField</code>, nullable
| <code>str | None</code>, default <code>None</code>
| Free-text annotation.
|}

== Enums ==

=== <code>SpecimenStatusOptions</code> values ===

The <code>status</code> enum (<code>str</code>). Two things to watch: <code>entered_in_error</code> uses an underscore rather than the FHIR hyphen, and <code>draft</code> is a Care addition with no FHIR equivalent.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Care-specific; not from FHIR
|-
| <code>available</code>
| Specimen available for testing
|-
| <code>unavailable</code>
| Specimen no longer available
|-
| <code>unsatisfactory</code>
| Specimen unsuitable for testing
|-
| <code>entered_in_error</code>
| Recorded in error
|}

== Nested JSON specs ==

These define the real structure behind the model's <code>JSONField</code>s.

=== <code>CollectionSpec</code> ===

Shape of the <code>collection</code> JSON field — a single collection event.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=Specimen|section=CollectionSpec|name=collector|type=UUID4 | None|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=collected_date_time|type=datetime | None|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=quantity|type=QuantitySpec | None|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=method|type=Coding | None bound to system-collection-method-code|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=procedure|type=UUID4 | None|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=body_site|type=Coding | None bound to system-body-site-observation|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=fasting_status_codeable_concept|type=Coding | None bound to system-fasting-status-code|notes=optional}}
{{Field|model=Specimen|section=CollectionSpec|name=fasting_status_duration|type=DurationSpec | None|notes=optional}}
|}

=== <code>ProcessingSpec</code> ===

One element of the <code>processing</code> list.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=Specimen|section=ProcessingSpec|name=description|type=str|notes=required}}
{{Field|model=Specimen|section=ProcessingSpec|name=method|type=Coding | None bound to system-specimen-processing-method-code|notes=optional}}
{{Field|model=Specimen|section=ProcessingSpec|name=performer|type=UUID4 | None|notes=optional}}
{{Field|model=Specimen|section=ProcessingSpec|name=time_date_time|type=str|notes=required}}
|}

=== <code>QuantitySpec</code> ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Specimen|section=QuantitySpec|name=value|type=Decimal|notes=<code>max_digits=20</code>, <code>decimal_places=0</code>, so integer-valued.}}
{{Field|model=Specimen|section=QuantitySpec|name=unit|type=Coding|notes=Required unit coding.}}
|}

This is a specimen-local quantity spec, distinct from the shared [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/quantity.py <code>Quantity</code>] common type — which allows <code>decimal_places=6</code>, optional <code>value</code>/<code>unit</code>, plus <code>code</code>/<code>meta</code>.

=== <code>DurationSpec</code> ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Specimen|section=DurationSpec|name=value|type=int|notes=Duration magnitude.}}
{{Field|model=Specimen|section=DurationSpec|name=unit|type=Coding|notes=Required unit coding.}}
|}

=== <code>Coding</code> (shared common type) ===

Every coded field above uses [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/coding.py <code>Coding</code>] (<code>extra="forbid"</code>):

{| class="wikitable"
|-
! Field
! Type
! Required
|-
| <code>system</code>
| <code>str | None</code>
| optional
|-
| <code>version</code>
| <code>str | None</code>
| optional
|-
| <code>code</code>
| <code>str</code>
| required
|-
| <code>display</code>
| <code>str | None</code>
| optional
|}

== Bound value sets ==

Coded fields bind to Care value sets via <code>ValueSetBoundCoding[<slug>]</code>, which validates the submitted <code>code</code> against the value set at write time.

{| class="wikitable"
|-
! Field
! Value set
! Slug
! Source system
|-
| <code>specimen_type</code>
| Specimen Type Code
| <code>system-specimen_type-code</code>
| HL7 v2-0487
|-
| <code>condition[]</code>
| Specimen Condition
| <code>system-specimen-condition-code</code>
| HL7 v2-0493 (v2.0.0)
|-
| <code>collection.method</code>
| Collection Method
| <code>system-collection-method-code</code>
| SNOMED CT (enumerated, see below)
|-
| <code>collection.body_site</code>
| Body Site
| <code>system-body-site-observation</code>
| (observation body-site value set)
|-
| <code>collection.fasting_status_codeable_concept</code>
| Fasting Status
| <code>system-fasting-status-code</code>
| HL7 v2-0916 (v2.0.0)
|-
| <code>processing[].method</code>
| Specimen Processing Method
| <code>system-specimen-processing-method-code</code>
| SNOMED CT (<code>< 9265001</code>)
|}

=== Collection Method value set ===

The <code>system-collection-method-code</code> value set enumerates these SNOMED CT codes:

{| class="wikitable"
|-
! Code
! Display
|-
| <code>129316008</code>
| Aspiration - action
|-
| <code>129314006</code>
| Biopsy - action
|-
| <code>129300006</code>
| Puncture - action
|-
| <code>129304002</code>
| Excision - action
|-
| <code>129323009</code>
| Scraping - action
|-
| <code>73416001</code>
| Urine specimen collection, clean catch
|-
| <code>225113003</code>
| Timed urine collection
|-
| <code>70777001</code>
| Urine specimen collection, catheterized
|-
| <code>386089008</code>
| Collection of coughed sputum
|-
| <code>278450005</code>
| Finger-prick sampling
|}

The other coded fields aren't enumerated. Fasting Status (<code>http://terminology.hl7.org/CodeSystem/v2-0916</code>), Specimen Condition (<code>v2-0493</code>), Specimen Type (<code>v2-0487</code>), Body Site, and Specimen Processing Method (SNOMED <code>< 9265001</code>) are pulled in by code-system reference or filter rather than a fixed concept list.

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which provides <code>serialize</code> (DB object → pydantic, via <code>get_database_mapping</code>) and <code>de_serialize</code> (pydantic → DB object), plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>__exclude__ = ["facility", "request"]</code> on the base keeps those fields from being copied field-for-field.

{| class="wikitable"
|-
! Spec class
! Role
! Key fields / behaviour
|-
| <code>BaseSpecimenSpec</code>
| shared base
| <code>id</code>, <code>accession_identifier</code>, <code>status</code> (required), <code>specimen_type</code> (required), <code>received_time</code>, <code>collection</code>, <code>processing</code>, <code>condition</code>, <code>note</code>. <code>__model__ = Specimen</code>, <code>__exclude__ = ["facility", "request"]</code>.
|-
| <code>SpecimenCreateSpec</code>
| write · create
| Adds <code>subject_patient: UUID4</code> (required), <code>subject_encounter: UUID4</code> (required), <code>request: UUID4 | None</code>. Wires up the FK links on creation.
|-
| <code>SpecimenUpdateSpec</code>
| write · update
| Relaxes <code>status</code> and <code>specimen_type</code> to optional (<code>| None</code>) for partial updates.
|-
| <code>SpecimenReadSpec</code>
| read · list
| Adds <code>specimen_definition: dict | None</code>. <code>perform_extra_serialization</code> sets <code>id = external_id</code> and, when present, embeds the linked specimen definition via <code>SpecimenDefinitionReadSpec.serialize(...).to_json()</code>.
|-
| <code>SpecimenRetrieveSpec</code>
| read · detail
| Extends <code>SpecimenReadSpec</code>, adds <code>service_request: dict | None</code>; serialization additionally embeds the linked service request via <code>ServiceRequestReadSpec.serialize(...).to_json()</code>.
|}

Nested specs (defined in the same module): <code>CollectionSpec</code>, <code>ProcessingSpec</code>, <code>QuantitySpec</code>, <code>DurationSpec</code> — see [[#nested-json-specs|Nested JSON specs]].

=== Validation & server behaviour ===

* <code>collection.collector</code> and <code>processing[].performer</code> must reference existing users by <code>external_id</code>; serialization then injects the resolved <code>collector_object</code> / <code>performer_object</code> (cached <code>UserSpec</code>).
* Coded fields are validated against their value sets on write (<code>ValueSetBoundCoding</code>); an unbound or invalid <code>code</code> is rejected.
* Read specs embed related resources — specimen definition on list and detail, service request on detail — as nested JSON rather than bare IDs.
* The base spec doesn't override <code>perform_extra_deserialization</code>, so no <code>status_history</code>-style server-side history is appended on write, unlike some other clinical resources.

== API integration notes ==

* Aligned with the FHIR <code>Specimen</code> resource, though some Care field names differ. On create, <code>subject_patient</code> / <code>subject_encounter</code> / <code>request</code> map to the <code>patient</code> / <code>encounter</code> / <code>service_request</code> FKs.
* The viewset (<code>SpecimenViewSet</code>) mixes in retrieve and update only (<code>EMRRetrieveMixin</code>, <code>EMRUpdateMixin</code>) — so you get read/detail/list and update, with <code>pydantic_model = BaseSpecimenSpec</code>, <code>pydantic_update_model = SpecimenUpdateSpec</code>, <code>pydantic_read_model = SpecimenReadSpec</code>, <code>pydantic_retrieve_model = SpecimenRetrieveSpec</code>.
* Filtering: <code>accession_identifier</code> (<code>icontains</code>); ordering on <code>created_date</code> / <code>modified_date</code>.
* The custom action <code>POST retrieve_by_accession_identifier</code> looks up a specimen by <code>accession_identifier</code> (must be ≥ 5 chars), returning a <code>SpecimenRetrieveSpec</code>. It raises a validation error on no match or multiple matches.
* Authorization keys off the linked <code>service_request</code>: read via <code>can_read_specimen</code>, write via <code>can_write_specimen</code>. One service request may own multiple specimens.

== Related models ==

<syntaxhighlight lang="text">facility → FK Facility (PROTECT, nullable) [excluded from specs]
patient → FK Patient (CASCADE) [set via subject_patient]
encounter → FK Encounter (CASCADE, nullable) [set via subject_encounter]
service_request → FK ServiceRequest (CASCADE, nullable) [set via request]
specimen_definition → FK SpecimenDefinition (CASCADE, nullable)</syntaxhighlight>
A <code>Specimen</code> is created to fulfill a [[References/Service Request|<code>ServiceRequest</code>]] (a lab order) and may be shaped by a [[References/Specimen Definition|<code>SpecimenDefinition</code>]] describing the expected sample. Results derived from a specimen surface through a [[References/Diagnostic Report|<code>DiagnosticReport</code>]].

{{Related}}

References/Specimen - Revision history

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

Admin: OHC identity seed