Functional standard / Interactions / PatientInstance
Assessment
A questionnaire or a calculator. The score is computed by the engine, never by the screen.
- Kind
- assessment
- Collection
- /v1/assessments
- Initial state
- pending
- Classification
- Operational
Scope and usage
Answers are stored here. On finalize, the score, band, and safety flag are set, and the score is written as an Observation. A safety flag raises an urgent task.
Boundaries and relationships
- The items, the kernel, and the bands live on the assessment Definition.
- The six kernels are the engine: weighted point sum, weight-banded dose, reference equation, logistic risk, exposure integral, boolean gate.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| assessment_type | 1..1 | code | R | questionnaire or calculator. Harness-owned from the definition. |
| encounter_id | 0..1 | id | — | Optional. An assessment need not belong to an encounter. |
| answers | 0..1 | object | — | Item key to answer. |
| taken_at | 1..1 | dateTime | — | When it was taken. |
| usage_id | 0..1 | id | R | Reference to the scoring run. Harness-owned. |
| result | 0..1 | object | R | Full kernel result. Harness-owned. |
| score | 0..1 | decimal | R | Harness-owned. |
| band | 0..1 | string | R | Harness-owned. |
| safety_flag | 1..1 | boolean | R | Harness-owned. |
State machine
pending/ initial — Opened.saved— Answers saved.finalized— Scored. Frozen.
pending → saved, finalized. saved → pending, finalized.
Frozen: finalized.
Invariants
ccs-asm-1— Finalize requires a complete answer set as defined by the instrument.ccs-asm-2— score, band, and safety_flag are refused if sent by the client.ccs-asm-3— A safety flag creates an urgent task. It does not create a diagnosis.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/assessments | List assessment. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/assessments | Create a assessment. Body is the resource minus harness-owned elements. |
| GET | /v1/assessments/{id} | Read one assessment. |
| PATCH | /v1/assessments/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/assessments/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/assessments/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
Notes
- Patients may create patient-reported assessments. Definition kind assessment.
Example
{ "patient_id": "pat_…", "definition_key": "phq9", "answers": { "item_1": 2, "item_2": 2 } }