Functional standard / What is being done / PatientInstance
CareAction
Something the patient does or receives: an order, referral, education, journal, medication, self-care, lifestyle, or appointment.
- Kind
- care_action
- Collection
- /v1/care-actions
- Initial state
- planned
- Classification
- Clinical in some uses
Scope and usage
The patient-facing line of a care plan. Orders, referrals, and medications are clinical. An appointment action records that a visit is part of care. The calendar itself is a connector.
Boundaries and relationships
- A Calendly booking may create or cancel an encounter. It does not replace this action when the action is the care plan's instruction to attend.
- A lab vendor is a ClinicalSetting plus a connector. The order is still this resource.
- Education content is the action. Publishing a document is ClinicalDocument.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| careplan_id | 0..1 | id | — | Plan this line belongs to. |
| action_type | 1..1 | code | B | order, referral, education, journal, medication, self_care, lifestyle, or appointment. |
| title | 1..1 | string | — | What the patient sees. |
| code | 0..1 | code | — | Service or order code. A billing connector may map this code to its item id. |
| details | 0..1 | object | — | Extra fields. Not a second clinical model. |
| setting_id | 0..1 | id | — | ClinicalSetting that fulfils an order or referral. |
| order_kind | 0..1 | code | B | lab, imaging, procedure, vaccination, or other. |
| order_status | 0..1 | code | B | proposed, signed, sent, resulted, or closed. Only a device actor may mark an order sent. |
| journal_plugin_key | 0..1 | code | — | Journal definition, when action_type is journal. |
| schedule | 0..1 | Schedule | — | every_days, anchor, until, grace_days. |
| completions | 0..* | dateTime | — | Times it was done. The harness uses these for due, overdue, and missed. |
State machine
planned/ initial — Not started.active— Under way.completed— Done. Frozen.cancelled— Withdrawn. Frozen.
planned → active, cancelled. active → completed, cancelled.
Frozen: completed and cancelled.
Terminology bindings
| Element | Strength | Values |
|---|---|---|
| action_type | required | order | referral | education | journal | medication | self_care | lifestyle | appointment |
Invariants
ccs-act-1— order, referral, and medication require a clinician. Other types do not.ccs-act-2— An external calendar may write an Encounter. It must not complete a clinical order.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/care-actions | List care action. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/care-actions | Create a care action. Body is the resource minus harness-owned elements. |
| GET | /v1/care-actions/{id} | Read one care action. |
| PATCH | /v1/care-actions/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/care-actions/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/care-actions/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
| GET | /v1/care-actions/{id}/schedule | Due, overdue, or missed from the cadence engine. |
Example
{ "patient_id": "pat_…", "action_type": "appointment", "title": "Review in 2 weeks" }