Functional standard / Interactions / PatientInstance
ClinicalDocument
A printable document that leaves the system: prescription, report, consent form, medical-legal note.
- Kind
- clinical_document
- Collection
- /v1/clinical-documents
- Initial state
- draft
- Classification
- Clinical in some uses
Scope and usage
Rendered from a template into HTML and an optional blob. Sharing with the patient needs data_sharing consent, and the document must be shareable, unprotected, and ready.
Boundaries and relationships
- The signed note is the NotePage. This is the document produced from it.
- A billing invoice is not this resource. Invoices stay in the billing system.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| doc_type | 1..1 | code | — | prescription, clinical_report, mlc, consent_form, diet_chart, or a local type. |
| title | 1..1 | string | — | Title. |
| source_kind | 0..1 | code | — | clinical_record, note_page, or assessment. |
| source_id | 0..1 | id | — | That source. |
| body_html | 0..1 | string | — | Rendered body. |
| header_html | 0..1 | string | — | Letterhead. Branding comes from the site profile when the template says so. |
| footer_html | 0..1 | string | — | Footer. |
| watermark | 0..1 | string | — | Watermark text. |
| blob_ref | 0..1 | uri | R | Where the file was stored. Harness-owned. |
| shareable_with_patient | 1..1 | boolean | — | Whether share is even offered. |
| protected | 1..1 | boolean | — | Protected documents are not shared through the portal. |
| signed | 1..1 | boolean | R | Harness-owned. |
| signed_by | 0..1 | id | R | Harness-owned. |
| expires_at | 0..1 | dateTime | — | Optional expiry. |
State machine
draft/ initial — Being composed.ready— Signed and releasable. Frozen. Clinical.expired— Past expires_at. Frozen.
draft → ready. ready → expired.
Frozen: ready and expired.
Invariants
ccs-doc-1— Share requires consent scope data_sharing, shareable_with_patient, not protected, and status ready.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/clinical-documents | List clinical document. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/clinical-documents | Create a clinical document. Body is the resource minus harness-owned elements. |
| GET | /v1/clinical-documents/{id} | Read one clinical document. |
| PATCH | /v1/clinical-documents/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/clinical-documents/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/clinical-documents/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
| POST | /v1/clinical-documents/{id}/share | Release to the patient when ccs-doc-1 holds. |
Notes
- Agents may create a draft. Definition kind clinical_document.
Example
{ "patient_id": "pat_…", "doc_type": "prescription", "title": "Prescription", "definition_key": "clinical_document_prescription" }