Functional standard / Interactions / PatientInstance
NotePage
One page of a record: a case sheet of blocks, or a chart of observations.
- Kind
- note_page
- Collection
- /v1/note-pages
- Initial state
- drafted
- Classification
- Clinical in some uses
Scope and usage
Draft, then optionally approve, then finalize. Finalizing writes observations for blocks that carry an observation code. After that, only addenda.
Boundaries and relationships
- An agent may create a draft and the page is marked ai_drafted until a person signs.
- Approval, when required, must be someone other than the requester.
- The canvas layout is template metadata plus sections. The normative content is blocks.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| record_id | 1..1 | id | I | Clinical record. Immutable. |
| page_type | 1..1 | code | B | case_sheet or chart. |
| title | 1..1 | string | — | Page title. |
| blocks | 0..1 | object | — | Block key to captured value. |
| chart | 0..1 | object | — | Chart query and component, when page_type is chart. |
| page_clinical_data | 0..* | object | — | Canvas sections. Values are also stored in blocks. |
| template_metadata | 0..1 | object | — | Template name and key for the canvas. |
| addenda | 0..* | Addendum | R | text, by, at. Harness-owned. Added only after finalize. |
| ai_drafted | 1..1 | boolean | R | True when an agent created the draft. Harness-owned. |
State machine
drafted/ initial — Being written.unapproved— Submitted, sent back, or waiting.approved— Countersigned. Frozen. Requires an approval.finalized— Signed into the record. Frozen. Clinical. Observations are written.
drafted → unapproved, approved, finalized. unapproved → drafted, approved. approved → finalized.
Frozen: approved and finalized.
Invariants
ccs-page-1— Required blocks must be filled before approve or finalize.ccs-page-2— A finalized page accepts addenda only. Blocks do not change.ccs-page-3— The approver is not the requester.ccs-page-4— On finalize, each block with an observation code becomes an Observation.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/note-pages | List note page. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/note-pages | Create a note page. Body is the resource minus harness-owned elements. |
| GET | /v1/note-pages/{id} | Read one note page. |
| PATCH | /v1/note-pages/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/note-pages/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/note-pages/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
| POST | /v1/note-pages/{id}/addenda | Append an addendum to a finalized page. Body is { text }. |
Notes
- Agents may create. Definition kind note_page.
Example
{ "patient_id": "pat_…", "record_id": "rec_…", "definition_key": "note_page_general_case_sheet", "title": "Case sheet" }