Laboratory & radiology

Diagnostic Report

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

3.1 · versioned documentation · 6 min read

A DiagnosticReport records the results and interpretation of a diagnostic test, tied to the ServiceRequest 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 (care/emr/models/diagnostic_report.py) imposes no shape: it persists category and code as opaque JSONFields and status as a free CharField. Shape and validation come from the Pydantic resource specs (care/emr/resources/diagnostic_report/) — the status enum, the coded-concept structure, the bound value sets, and the separate read/write API schemas. The specs build on EMRResource and serialize between the API and the model.

Source:

• Model: care/emr/models/diagnostic_report.py
• Spec: care/emr/resources/diagnostic_report/spec.py
• Valueset: care/emr/resources/diagnostic_report/valueset.py

Models

DiagnosticReport extends EMRBaseModel, the shared MANSOQ EMR base that provides external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and history/meta JSON.

DiagnosticReport fields

Classification

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

Narrative

Relationships

Enum values

DiagnosticReportStatusChoices

From spec.py. (modified is defined in source but commented out and is not an active value.)

Bound value sets

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

Resource specs (API schema)

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

DiagnosticReportRetrieveSpec.perform_extra_serialization (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 ListSpec hook (sets id, embeds service_request).
• serialize_audit_users → populates created_by / updated_by from cache (UserSpec).
• observations → all Observation rows where diagnostic_report == obj, each via ObservationRetrieveSpec.serialize(...).
• requester → if service_request.requester_id is set, loaded from cache via UserSpec.
• encounter → EncounterListSpec.serialize(obj.encounter), with encounter["patient"] set to PatientRetrieveSpec.serialize(obj.encounter.patient, facility=obj.facility).

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

Related models

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

diagnostic_report
  facility        → FK facility.Facility (PROTECT, nullable)
  patient         → FK emr.Patient (CASCADE)
  encounter       → FK emr.Encounter (CASCADE)
  service_request → FK emr.ServiceRequest (CASCADE)

Deleting a Patient, Encounter, or ServiceRequest cascades to its diagnostic reports; the facility link is PROTECTed. Routine deletes are soft, via EMRBaseModel. On retrieve, related Observation records are pulled in through the reverse FK (Observation.diagnostic_report).

Methods & save behaviour

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

API integration notes

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

Related

• Reference: Service Request
• Reference: Observation
• Reference: Specimen
• Reference: Encounter
• Reference: Patient
• Reference: Base Model
• Source: diagnostic_report.py on GitHub
• Source: resources/diagnostic_report/spec.py on GitHub
• Source: resources/diagnostic_report/valueset.py 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/clinical/diagnostic-report.mdx:1 · f6e9f05f