Functional standard / Governance / Instance
Definition
A versioned template. Packs ship published definitions. A site publishes its own, and a site key overrides the library key.
- Kind
- definition
- Collection
- /v1/definitions
- Initial state
- draft
- Classification
- Operational
Scope and usage
This is the profiling mechanism. Eighteen def_kind values constrain other resources the way an openEHR archetype constrains a reference-model class, and the way a FHIR profile constrains a resource. The config object is the constraint. See Definitions in this standard.
Boundaries and relationships
- A published definition is frozen. A change is a new draft of the same key, with the next version.
- Library rows live at site * and are read-only.
- patient_fields and reaction do not instantiate a resource. They configure the harness.
Resource content
Elements this resource adds. It also carries the Instance.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| def_kind | 1..1 | code | I | Which template. Immutable. |
| key | 1..1 | code | I | Stable key. Immutable. Site overrides library on the same key. |
| version | 1..1 | integer | R | Harness assigns the next version. |
| name | 1..1 | string | — | Display name. |
| description | 0..1 | string | — | What a configurer needs to know. |
| config | 1..1 | object | — | Kind-specific constraint. See that definition kind. |
| pack_id | 0..1 | code | R | Set when loaded from a pack. Harness-owned. |
| review_status | 0..1 | code | R | Clinical review result: draft, approved, or rejected. Harness-owned. |
| reviewed_by | 0..1 | id | R | Reviewer. Must not be the author. Harness-owned. |
| reviewed_at | 0..1 | dateTime | R | When reviewed. Harness-owned. |
| review_ref | 0..1 | string | R | Reference for the review. Harness-owned. |
| review_notes | 0..1 | string | R | Reviewer's notes. Harness-owned. |
State machine
draft/ initial — Editable.published— In use. Frozen.retired— No longer offered for new instances. Frozen.
draft → published. published → retired.
Frozen: published and retired.
Invariants
ccs-def-1— Published and retired definitions cannot be edited.ccs-def-2— config is validated against the schema for def_kind.ccs-def-3— A site definition with the same key is preferred over the pack definition.ccs-def-4— In production mode, an instance cannot be created from a definition that is not clinically approved.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/definitions | List definition. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/definitions | Create a definition. Body is the resource minus harness-owned elements. |
| GET | /v1/definitions/{id} | Read one definition. |
| PATCH | /v1/definitions/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/definitions/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/definitions/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
Example
{
"def_kind": "cohort",
"key": "cohort_htn",
"name": "Hypertension",
"config": { "rule": "cond_htn or obs_bp_systolic >= 140", "manual_only": false, "protocols": ["proto_htn"] }
}