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

2026-07-06T04:03:31Z

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

← Older revision		Revision as of 09:33, 6 July 2026
Line 222:		Line 222:
	* <code>note</code> and <code>conclusion</code> carry human-readable narrative and are not parsed by the platform.		* <code>note</code> and <code>conclusion</code> carry human-readable narrative and are not parsed by the platform.
	* The detail (<code>Retrieve</code>) payload embeds the linked service request, its requester, the encounter (with patient), audit users, and all child observations — none of which are writable.		* The detail (<code>Retrieve</code>) payload embeds the linked service request, its requester, the encounter (with patient), audit users, and all child observations — none of which are writable.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:20Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Diagnostic Report
|order=7
|introduced=3.0
|fhir=DiagnosticReport
|model=DiagnosticReport
|reference=References/Base models & conventions
}}

A <code>DiagnosticReport</code> records the results and interpretation of a diagnostic test, tied to the <code>ServiceRequest</code> that ordered it. You create one to report on an investigation, then read it back with its observations, encounter, and requester embedded.

The Django model (<code>care/emr/models/diagnostic_report.py</code>) imposes no shape: it persists <code>category</code> and <code>code</code> as opaque <code>JSONField</code>s and <code>status</code> as a free <code>CharField</code>. Shape and validation come from the Pydantic resource specs (<code>care/emr/resources/diagnostic_report/</code>) — the status enum, the coded-concept structure, the bound value sets, and the separate read/write API schemas. The specs build on <code>EMRResource</code> and serialize between the API and the model.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/diagnostic_report.py <code>care/emr/models/diagnostic_report.py</code>]
* Spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/diagnostic_report/spec.py <code>care/emr/resources/diagnostic_report/spec.py</code>]
* Valueset: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/diagnostic_report/valueset.py <code>care/emr/resources/diagnostic_report/valueset.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>DiagnosticReport</code>
| Results and interpretation of a diagnostic test or investigation, tied to a <code>ServiceRequest</code>
|}

<code>DiagnosticReport</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that provides <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>DiagnosticReport</code> fields ==

=== Classification ===

{| class="wikitable"
|-
! Field
! Model type
! Spec shape
! Notes
|-
| <code>status</code>
| <code>CharField(255)</code>
| <code>DiagnosticReportStatusChoices</code> (enum, required)
| Lifecycle status. Stored as free text but constrained to the enum below on write. Optional on update.
|-
| <code>category</code>
| <code>JSONField</code> (null)
| <code>Coding { system, version?, code, display? }</code>, '''required'''
| Service section the report belongs to. <code>code</code> is validated against the '''Diagnostic Service Sections''' value set.
|-
| <code>code</code>
| <code>JSONField</code> (null)
| <code>Coding { system, version?, code, display? }</code>, optional
| The test or panel performed. <code>code</code> is validated against the '''Observation''' value set (LOINC). Nullable.
|}

The <code>Coding</code> shape (from <code>care/emr/resources/common/coding.py</code>, <code>extra="forbid"</code>):

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=DiagnosticReport|section=Classification|name=system|type=str|notes=optional}}
{{Field|model=DiagnosticReport|section=Classification|name=version|type=str|notes=optional}}
{{Field|model=DiagnosticReport|section=Classification|name=code|type=str|notes='''required'''}}
{{Field|model=DiagnosticReport|section=Classification|name=display|type=str|notes=optional}}
|}

=== Narrative ===

{| class="wikitable"
|-
! Field
! Model type
! Spec shape
! Notes
|-
| <code>note</code>
| <code>TextField</code> (null)
| <code>str | None</code>
| Free-text comments. Not parsed by the platform.
|-
| <code>conclusion</code>
| <code>TextField</code> (null)
| <code>str | None</code>
| Clinical interpretation/summary of the results. Not parsed by the platform.
|}

=== Relationships ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=DiagnosticReport|section=Relationships|name=facility|type=FK → facility.Facility|notes=<code>PROTECT</code>, nullable. Facility the report is scoped to. Set server-side; not a writable spec field.}}
{{Field|model=DiagnosticReport|section=Relationships|name=patient|type=FK → emr.Patient|notes=<code>CASCADE</code>. Subject of the report. Set server-side; not a writable spec field.}}
{{Field|model=DiagnosticReport|section=Relationships|name=encounter|type=FK → emr.Encounter|notes=<code>CASCADE</code>. Encounter the report was produced under. Set server-side; not a writable spec field.}}
{{Field|model=DiagnosticReport|section=Relationships|name=service_request|type=FK → emr.ServiceRequest|notes=<code>CASCADE</code>. The order this report fulfils. Write-only on create (resolved from <code>external_id</code>); excluded from base serialization via <code>__exclude__</code>.}}
|}

== Enum values ==

=== <code>DiagnosticReportStatusChoices</code> ===

From <code>spec.py</code>. (<code>modified</code> is defined in source but commented out and is '''not''' an active value.)

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>registered</code>
| Report exists / has been registered
|-
| <code>partial</code>
| Some results available, report incomplete
|-
| <code>preliminary</code>
| Provisional results pending verification
|-
| <code>final</code>
| Verified, complete report
|}

== Bound value sets ==

Coded fields validate their <code>code</code> against a registered Care value set (<code>ValueSetBoundCoding</code>). A <code>code</code> outside the bound set is rejected at deserialization.

{| class="wikitable"
|-
! Field
! Value set
! Slug
! Included system(s)
|-
| <code>category</code>
| Diagnostic Service Sections
| <code>system-diagnostic-service-sections-code</code>
| <code>http://terminology.hl7.org/CodeSystem/v2-0074</code>
|-
| <code>code</code>
| Observation
| <code>system-observation</code>
| <code>http://loinc.org</code>
|}

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>) through <code>DiagnosticReportSpecBase</code>. <code>serialize</code> builds the read payload from the model (mapping <code>external_id</code> → <code>id</code>); <code>de_serialize</code> writes spec fields back to the model. The <code>perform_extra_serialization</code>/<code>perform_extra_deserialization</code> hooks handle server-side behaviour — resolving foreign keys on write, embedding related resources on read.

{| class="wikitable"
|-
! Spec class
! Role
! Fields / behaviour
|-
| <code>DiagnosticReportSpecBase</code>
| shared base
| <code>id?</code>, <code>status</code> (enum, required), <code>category</code> (bound Coding, required), <code>code?</code> (bound Coding), <code>note?</code>, <code>conclusion?</code>. <code>__model__ = DiagnosticReport</code>, <code>__exclude__ = ["service_request"]</code>.
|-
| <code>DiagnosticReportCreateSpec</code>
| write · create
| Base + <code>service_request: UUID4</code> (required, the request's <code>external_id</code>). <code>perform_extra_deserialization</code> resolves it via <code>get_object_or_404(ServiceRequest, external_id=...)</code> and sets <code>obj.service_request</code>.
|-
| <code>DiagnosticReportUpdateSpec</code>
| write · update
| Base, but <code>status</code> is optional (<code>DiagnosticReportStatusChoices | None</code>). <code>service_request</code> is '''not''' writable on update.
|-
| <code>DiagnosticReportListSpec</code>
| read · list
| Base + <code>created_date</code>, <code>modified_date</code>, <code>service_request: dict | None</code>. <code>perform_extra_serialization</code> sets <code>id = external_id</code> and embeds the linked request via <code>BaseServiceRequestSpec.serialize(...)</code>.
|-
| <code>DiagnosticReportRetrieveSpec</code>
| read · detail
| Extends <code>ListSpec</code> + <code>observations: list[dict]</code>, <code>encounter: dict</code>, <code>created_by?</code>, <code>updated_by?</code>, <code>requester?</code>. See serialization below.
|}

=== <code>DiagnosticReportRetrieveSpec.perform_extra_serialization</code> (server-side, read) ===

The detail read enriches the list payload so a viewer gets the report, its observations, and its context in one call:

* Calls the <code>ListSpec</code> hook (sets <code>id</code>, embeds <code>service_request</code>).
* <code>serialize_audit_users</code> → populates <code>created_by</code> / <code>updated_by</code> from cache (<code>UserSpec</code>).
* <code>observations</code> → all <code>Observation</code> rows where <code>diagnostic_report == obj</code>, each via <code>ObservationRetrieveSpec.serialize(...)</code>.
* <code>requester</code> → if <code>service_request.requester_id</code> is set, loaded from cache via <code>UserSpec</code>.
* <code>encounter</code> → <code>EncounterListSpec.serialize(obj.encounter)</code>, with <code>encounter["patient"]</code> set to <code>PatientRetrieveSpec.serialize(obj.encounter.patient, facility=obj.facility)</code>.

These embedded fields (<code>service_request</code>, <code>observations</code>, <code>encounter</code>, <code>requester</code>, audit users) are '''read-only''' and are not accepted on create/update.

== Related models ==

<code>DiagnosticReport</code> is the only model defined in this file. It sits downstream of a <code>ServiceRequest</code> and is anchored to a patient and encounter:

<syntaxhighlight lang="text">diagnostic_report
facility → FK facility.Facility (PROTECT, nullable)
patient → FK emr.Patient (CASCADE)
encounter → FK emr.Encounter (CASCADE)
service_request → FK emr.ServiceRequest (CASCADE)</syntaxhighlight>
Deleting a <code>Patient</code>, <code>Encounter</code>, or <code>ServiceRequest</code> cascades to its diagnostic reports; the <code>facility</code> link is <code>PROTECT</code>ed. Routine deletes are soft, via <code>EMRBaseModel</code>. On retrieve, related <code>Observation</code> records are pulled in through the reverse FK (<code>Observation.diagnostic_report</code>).

== Methods & save behaviour ==

* '''Create''' (<code>DiagnosticReportCreateSpec.de_serialize</code>): writes <code>status</code>, <code>category</code>, <code>code</code>, <code>note</code>, <code>conclusion</code> onto the model; <code>perform_extra_deserialization</code> resolves <code>service_request</code> from its <code>external_id</code> (404 if missing). <code>facility</code>, <code>patient</code>, and <code>encounter</code> come from the request context in the view layer, not the payload.
* '''Update''' (<code>DiagnosticReportUpdateSpec</code>): same base fields, but <code>status</code> is optional, so a partial status change is allowed. <code>service_request</code> cannot be reassigned.
* '''Read''' (<code>List</code>/<code>Retrieve</code>): no model writes; all enrichment happens in <code>perform_extra_serialization</code> (see above). User and service-request lookups go through the serializer cache (<code>model_from_cache</code>).
* Coded fields are validated at deserialization: <code>category.code</code> must be in the Diagnostic Service Sections value set; <code>code.code</code> (when present) must be in the Observation value set. <code>status</code> must be a <code>DiagnosticReportStatusChoices</code> value.

== API integration notes ==

* Diagnostic reports are exposed through Care's REST API and align with the FHIR <code>DiagnosticReport</code> resource; payload field names follow the spec classes above.
* <code>category</code> and <code>code</code> are coded concepts (<code>Coding</code>: <code>system</code>/<code>code</code>/<code>display</code>), not free strings. Populate <code>code</code> from the bound value set — anything outside it is rejected, and <code>Coding</code> forbids extra keys.
* <code>status</code> is stored as a free <code>CharField</code>, but the spec restricts writes to the <code>DiagnosticReportStatusChoices</code> enum (<code>registered</code>, <code>partial</code>, <code>preliminary</code>, <code>final</code>).
* A report fulfils exactly one <code>service_request</code>. Create the [[References/Service Request]] first, then pass its <code>external_id</code> as <code>service_request</code> on create.
* <code>note</code> and <code>conclusion</code> carry human-readable narrative and are not parsed by the platform.
* The detail (<code>Retrieve</code>) payload embeds the linked service request, its requester, the encounter (with patient), audit users, and all child observations — none of which are writable.

{{Related}}

References/Diagnostic Report - Revision history

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

Admin: OHC identity seed