Clinical Intelligence StandardsVersion 0.2

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

Resource content

Elements this resource adds. It also carries the Instance, including patient_id.

NameCard.TypeFlagsDescription
assessment_type1..1codeRquestionnaire or calculator. Harness-owned from the definition.
encounter_id0..1id—Optional. An assessment need not belong to an encounter.
answers0..1object—Item key to answer.
taken_at1..1dateTime—When it was taken.
usage_id0..1idRReference to the scoring run. Harness-owned.
result0..1objectRFull kernel result. Harness-owned.
score0..1decimalRHarness-owned.
band0..1stringRHarness-owned.
safety_flag1..1booleanRHarness-owned.

State machine

pending → saved, finalized. saved → pending, finalized.

Frozen: finalized.

Invariants

Operations

MethodPathMeaning
GET/v1/assessmentsList assessment. Filter by patient_id, status, and where the model has them, encounter_id or definition_key.
POST/v1/assessmentsCreate 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}/transitionMove 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

Example

{ "patient_id": "pat_…", "definition_key": "phq9", "answers": { "item_1": 2, "item_2": 2 } }