References/Healthcare Service

referencefacilityCARE 3.0+

A HealthcareService is a service a facility offers — cardiology, lab, radiology, pharmacy — scoped to one or more locations and to the facility organization that manages it. You touch it when modeling what a facility provides and where.

The Django model is thin storage: service_type and styling_metadata are opaque JSONFields. Their real structure lives in the Pydantic resource specs, which also define the bound value set, the internal_type enum, and the separate read and write API schemas.

Source:

Model: [https://github.com/ohcnetwork/care/blob/develop/care/emr/models/healthcare_service.py care/emr/models/healthcare_service.py]
Spec: [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/healthcare_service/spec.py care/emr/resources/healthcare_service/spec.py]
Value set: [https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/healthcare_service/valueset.py care/emr/resources/healthcare_service/valueset.py]

Models

Model	Purpose
`HealthcareService`	A service a facility offers (e.g. cardiology, lab, radiology), scoped to locations and a managing organization

HealthcareService extends EMRBaseModel, the shared Care EMR base that provides external_id, audit fields, soft-delete via deleted, created_by/updated_by, and history/meta JSON.

`HealthcareService` fields

Identity & classification

Field	Type	Notes
`name`	`CharField(1024)`	Display name. Required on write; no default
`service_type`	`JSONField → Coding`	Holds one FHIR-style `Coding` object, not a string. Defaults to `{}`. In the API it is a `ValueSetBoundCoding` bound to the Healthcare Service Type Code value set (below). Optional (`None`)
`internal_type`	`CharField(255)`	Nullable, default `None`. The API constrains it to the `HealthcareServiceInternalType` enum (`pharmacy` / `lab` / `scheduling` / `store`); the column does not
`extra_details`	`TextField`	Free text. Not nullable and no DB default, so write specs require a value — an empty string counts

Scope & placement

Field	Type	Notes
`facility`	`FK → facility.Facility`	`PROTECT`; nullable (`default=None`, `blank=True`). Excluded from every spec (`__exclude__ = ["facility"]`) and set server-side from the URL context — never from the request body
`locations`	`ArrayField[int]`	Defaults to `[]`. Holds `FacilityLocation` primary-key integers, not FK rows. Write specs take location `external_id`s (UUIDs); retrieve specs return serialized location objects
`managing_organization`	`FK → emr.FacilityOrganization`	`PROTECT`; nullable. The facility-scoped org (department/team) responsible for the service. Write specs take its `external_id` (UUID), resolved server-side

Presentation

Field	Type	Notes
`styling_metadata`	`JSONField → dict`	Nullable in the DB; defaults to `{}` in the specs. An open JSON bag of UI hints (colors, icons) with no backend semantics

Coded field shapes (JSON fields)

`service_type` → `Coding`

service_type stores a single Coding object. In the API it is a ValueSetBoundCoding whose code is checked against the Healthcare Service Type Code value set during de-serialization. Optional (None).

Coding {
  system:  str | None        # e.g. "http://terminology.hl7.org/CodeSystem/service-type"
  version: str | None
  code:    str               # required; validated against the bound value set
  display: str | None
}
# extra="forbid" — unknown keys rejected

Bound value set — Healthcare Service Type Code

Property	Value
Name	`Healthcare Service Type Code`
Slug	`healthcare-service-type-code`
Status	`active`
Compose / include system	`http://terminology.hl7.org/CodeSystem/service-type`
System version	`2.0.0`

Registered via register_valueset(...) and register_as_system(). The service_type.code on create or update must resolve within this value set.

Enums

`HealthcareServiceInternalType` values

Constrains internal_type in the specs (str enum). The model column is a plain CharField, so legacy or other values may already exist in storage.

Value
`pharmacy`
`lab`
`scheduling`
`store`

Related models

`facility.Facility`

facility → FK Facility (PROTECT, nullable)

The facility offering the service. PROTECT blocks deleting a facility that still has healthcare services. Excluded from specs and set from the request context. See References/Facility.

`emr.FacilityOrganization`

managing_organization → FK FacilityOrganization (PROTECT, nullable)

The facility-scoped organization (department/team) that owns the service. Write specs take its external_id (UUID); the retrieve spec embeds it, serialized via FacilityOrganizationReadSpec. See References/Organization.

Locations

locations is an ArrayField of integer PKs, not a relational join — each entry references a FacilityLocation row by primary key, with resolution and validation handled in application code rather than by a database foreign key. Write specs take location external_ids (UUIDs); the retrieve spec embeds each location, serialized via FacilityLocationListSpec. See References/Location.

Resource specs (API schema)

Every spec extends EMRResource (care/emr/resources/base.py), which provides serialize (DB object → spec) and de_serialize (spec → DB object), plus the perform_extra_serialization / perform_extra_deserialization hooks. __exclude__ = ["facility"] keeps facility out of every payload.

Spec class	Role	Notes
`BaseHealthcareServiceSpec`	shared base	Fields: `id`, `service_type`, `internal_type`, `name`, `styling_metadata`, `extra_details`. `__model__ = HealthcareService`, `__exclude__ = ["facility"]`
`HealthcareServiceWriteSpec`	write · create & update	None. Resolves `managing_organization` from its `external_id` in `perform_extra_deserialization`
`HealthcareServiceReadSpec`	read · list	Base fields. `perform_extra_serialization` sets `id` to `obj.external_id`
`HealthcareServiceRetrieveSpec`	read · detail	None (serialized via `FacilityOrganizationReadSpec`)

Field exposure by spec

Field	Base	Write	Read (list)	Retrieve (detail)
`id` (UUID4)	✓ (read-only)	✓	✓ (= `external_id`)	✓ (= `external_id`)
`name` (str, required)	✓	✓	✓	✓
`service_type` (bound `Coding`, optional)	✓	✓	✓	✓
`internal_type` (enum, optional)	✓	✓	✓	✓
`styling_metadata` (dict, default `{}`)	✓	✓	✓	✓
`extra_details` (str, required)	✓	✓	✓	✓
`locations`	—	`list[UUID4]` (write)	—	`list[dict]` (embedded)
`managing_organization`	—	None (write)	—	None (embedded)

Validation & server-side behaviour

service_type — a ValueSetBoundCoding. De-serialization runs validate_valueset on code against the healthcare-service-type-code value set, and extra="forbid" on the underlying Coding rejects unknown keys.
managing_organization (write) — perform_extra_deserialization resolves the UUID via get_object_or_404(FacilityOrganization, external_id=...) and assigns the FK; a falsy value sets managing_organization = None.
locations (write) — submitted as UUIDs. The retrieve spec resolves each PK back to a FacilityLocation and serializes it, silently skipping any that fail to load (try/except … pass).
id / external_id — never written from the body. de_serialize skips both; serialize / perform_extra_serialization populate id from obj.external_id.
facility — excluded from all specs and assigned server-side, so it can't be set or changed through the API body.
No status field, and therefore no server-maintained status_history.

Methods & save behaviour

Inherits save(), soft-delete (deleted), audit fields (created_by/updated_by), history/meta, and external_id from EMRBaseModel.
EMRResource.serialize / de_serialize drive read/write conversion; the extra (de)serialization hooks above handle FK resolution and embedded serialization.
facility and managing_organization use on_delete=PROTECT, so deleting either while a service references it is blocked at the DB level.

API integration notes

The API surface is built from the spec classes, not the raw model. Three things commonly trip up integrators:

service_type takes a Coding object whose code is in the bound value set, not a bare string.
On write, locations and managing_organization are external_ids (UUIDs); detail responses embed the full objects. Nothing at the DB level confirms the referenced locations belong to the same facility.
facility is never accepted in the request body — it's set from the URL context.

Pages that link here:

Concepts/Healthcare Service

Reference: References/Base models & conventions

Wiki: ohcnwiki.tellmey.fyi