Functional standard / People / Instance
Patient
The person the whole record is about. Family members are patients too, linked by Relationship.
- Kind
- patient
- Collection
- /v1/patients
- Initial state
- active
- Classification
- Clinical
Scope and usage
Register the person once per site. Demographics, identifiers, and whether they can act as a guardian or care-taker live here. Age is computed from date of birth, or from an age recorded on a date, so a stored age does not go stale.
Boundaries and relationships
- A family member is another Patient, not a nested person. Link them with Relationship.
- The login of a patient is an Actor with role patient. This resource is the clinical person, not the credential.
- Site-specific form fields are not columns. They come from a patient_fields Definition into demographics and custom_fields.
Resource content
Elements this resource adds. It also carries the Instance.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| name | 1..1 | string | — | Name used by the care team. |
| country | 1..1 | code | B | ISO country, at least two characters. |
| gender | 1..1 | code | B | male, female, other, or unknown. |
| date_of_birth | 0..1 | date | — | Provide this or age_years. |
| age_years | 0..1 | integer | — | Age on age_recorded_on, from 0 to 130. Used when date of birth is unknown. |
| age_recorded_on | 0..1 | date | — | The day age_years was recorded. |
| age_is_estimated | 1..1 | boolean | — | True when the age was estimated. |
| age | 0..1 | integer | R | Computed. Not accepted on create or update. |
| demographics | 0..1 | object | — | Standard optional fields the site has enabled: phone, language, occupation, and others. |
| custom_fields | 0..1 | object | — | Fields declared only by this site's patient_fields definition. |
| identifiers | 0..1 | object | — | External ids, for example { mrn, abha }. |
| is_guardian | 1..1 | boolean | — | This person may be named as a guardian on a Relationship. |
| is_care_taker | 1..1 | boolean | — | This person may be named as a care-taker. |
State machine
active/ initial — Receiving or eligible for care at this site.inactive— Not currently in care. Can return to active.deceased— Death has been recorded. Terminal for care. Clinical.
active → inactive, deceased. inactive → active, deceased.
Frozen: The resource is not frozen by status. It is not deletable.
Terminology bindings
| Element | Strength | Values |
|---|---|---|
| gender | required | male | female | other | unknown |
Invariants
ccs-pat-1— country, gender, and either date_of_birth or age_years are required.ccs-pat-2— A patient actor may read and write only their own record and patients they actively represent.ccs-pat-3— status deceased requires a clinician.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/patients | List patient. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/patients | Create a patient. Body is the resource minus harness-owned elements. |
| GET | /v1/patients/{id} | Read one patient. |
| PATCH | /v1/patients/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/patients/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| GET | /v1/patients/{id}/summary | Profiles, what is present and absent, and pending actions. |
| GET | /v1/patients/{id}/facts | Facts used by cohort rules: age, gender, conditions, latest observations. |
| GET | /v1/patients/{id}/timeline | Hash-chained audit for this patient. |
| GET | /v1/patients/{id}/timeline/verify | Checks the chain. Reports the first broken entry. |
| POST | /v1/patients/{id}/suggest-cohorts | Proposes cohort memberships whose rules match. Does not enroll. |
Notes
- Creating a patient also creates the general health profile when the pack defines one.
Example
{
"name": "Asha K",
"country": "IN",
"gender": "female",
"age_years": 34,
"identifiers": { "mrn": "MRN-1044" }
}