Skip to content

Composition Profile

Canonical../StructureDefinition/nexus-emr-core-composition
Statusdraft · 1.26.0
BaseComposition (constraint)
SourceFSH · JSON

Nexus EMR profile for an AUTHORED clinical note -- principally the encounter note (progress note, consult note, telephone note) written by an EMR user or drafted by an AI scribe and attested by a clinician.

Overview

Narrative lives in FHIR as XHTML in section.text, not as an encoded attachment, so a note is readable and queryable without dereferencing a blob. status carries the draft / signed / amended lifecycle, and amendments are expressed as version history over one resource rather than as a chain of related resources.

Use DocumentReference instead for documents that arrive as opaque files -- scans, PDFs, faxes, Word documents -- where FHIR holds metadata and a pointer to bytes. The two profiles partition the clinical-document space; neither is a fallback for the other.

Read machine authorship from the AIAST security label in meta.security. Nexus EMR also writes a typed/scribe marker in meta.tag, at an address this guide does not publish, which is a second answer to the question the label already settles; that second axis is tracked as FHIR-385. Read meta.security, and do not read the absence of the meta.tag marker as human-typed -- absent means the origin was not recorded.

Overview

NexusEmrCoreComposition models an authored clinical note -- the encounter note, consult note, or telephone note that an EMR user writes, or that an AI scribe drafts and a clinician signs.

The narrative lives in FHIR, as XHTML in section.text. A note is therefore readable, searchable and diffable without dereferencing a blob, and the lifecycle (draft -> signed -> amended) is expressed by Composition.status rather than invented in an extension.

Composition or DocumentReference?

The two profiles partition the clinical-document space. Neither is a fallback for the other.

Composition DocumentReference
What it is a note we authored a document that arrived as a file
Content XHTML text in section.text bytes behind content.attachment.url
Examples progress note, consult note, telephone note scan, fax, external PDF letter, consent form
Lifecycle status: preliminary / final / amended status: current / superseded
Readable without a second fetch? yes no

The test is not "is it clinical" -- both are. It is did we write it, and is the content text we control? A scanned consult letter is a DocumentReference even though a human wrote it, because what we hold is a TIFF. A dictated-then-transcribed progress note is a Composition even though a machine produced the text, because we hold the text.

The note lifecycle

status is the answer to "is this note signed?". There is no extension for it and none should be created.

Note state status
draft, being typed preliminary
signed final
signed, then edited amended
voided / created in error entered-in-error

Once status is final or amended, the note must carry an attester with mode legal or professional (invariant composition-signed-has-attester). A signed note with nobody identified as having signed it is not a record anyone can stand behind.

Amendments are version history

When a signed note is edited, update the same resource in place and set status to amended. The server's version history preserves the as-signed content. The business identifier does not change.

Do not create a second Composition and relate it back. That leaves two resources where the chart must know to display one, and every consumer has to learn to filter.

relatesTo is deliberately left unprofiled, so it remains available in core R4 if a true addendum workflow later appears -- original untouched, new signed content appended with its own author and sign-off. That is a different clinical act from an in-place correction, and it is not the mechanism for ordinary amendment.

This model depends on infrastructure the IG has not yet declared

Version history is server-local. _history does not travel in bundles, $everything, or sync pipelines -- all of which move current versions only. Across a system boundary an amended note arrives as its amended text, with the as-signed content absent.

The nexus-emr-server CapabilityStatement now declares the interaction set for Composition, so "which interactions may I use" is answerable from the artifacts. What it does not declare is a versioning policy: it carries no versioning element and lists neither vread nor history-instance, so whether prior versions are retrievable at all remains server-specific. And meta.versionId is type id -- server-opaque in R4, unconstrained here. Consumers must not infer ordering, authorship, or "which version was signed" by parsing or sorting versionId.

Reconstructing the as-signed note is, today, reliable only on the authoring server. Declaring the version-history contract is outstanding IG work and a prerequisite for relying on this model across boundaries.

Dating a note

A note carries three dates, and they answer three different questions. The one most readers want is not the one they find first.

event.period.start is the clinical date: when the documented care actually happened. It does not move. It is the first arm of the profile's declared effective date (event.period.start | date), and it is what a chart timeline should sort by.

date is the composition editing time and it moves when the note is amended. It is only the fallback arm, reached when event is absent -- so a note that leaves event empty will re-position on a timeline to the date of its own amendment. Populate event whenever the note documents care that happened at an identifiable time, which for a progress note, a consult note or a discharge summary is always.

attester.time is the third: when the signature happened.

If you need a stable "when was this written" -- a fourth question none of the three answers:

  • the encounter's period, where the note is linked to an encounter; or
  • the date of the earliest version in history (which needs the capability above).

AI-drafted notes

A Device may appear in author alongside the human. This is one of two mechanisms for recording that a note was scribed rather than typed; the other is a Provenance record, which carries the fuller trail (model, inputs, supervising human). They are not exclusive, and the IG does not yet rule on which one consumers should read -- that is blocked on what the consuming code actually needs.

Two rules that do hold today:

  • The attester is always the clinician, never the Device. A Device may author; it cannot attest. Generation and responsibility are different acts, which is why they are different elements.
  • Absent a Device author means origin unknown, not "typed." Notes migrated from OSCAR Pro carry no origin information and must not be inferred to be human-typed.

Open: how a Device author is referenced

Whether AI agents are registered as Device resources in this FHIR store, whether one static Device denotes "a Nexus AI agent", or whether the reference is by identifier into the AI Harness's own graph with no resource on this server, is unresolved and being worked with the harness team. This profile deliberately does not constrain it.

Sections

section.code is bound, extensible, to the Composition Section Value Set. It says what a section clinically IS. The codes are the C-CDA on FHIR / IPS section vocabulary restricted to what primary care produces: a vital signs section is LOINC 8716-3, a problem list 11450-4.

It is not the place for a document-type code. LOINC supplies both document codes and section codes, out of one system and in one format, and nothing about a code says which axis it belongs to -- 34109-9 "Note" types a DOCUMENT and does not belong in a section slot. That is the mistake the extensible strength exists to catch. The cost is accepted: a legitimate section kind the set does not yet name warns too, and growing the set is one line.

A section answers three independent questions and each has its own element: what it clinically is (section.code), who produced it (section.author), and how to render it (the block-type extension). They are not interchangeable.

section.entry is declared but expected to be sparse today. It is the element that will carry structured note generation when it arrives -- a scribe filling a structured template, or SDC extraction promoting answers to Observation / Condition -- which is why it is present now rather than discovered later.

section.text must conform to the FHIR Narrative rules: XHTML, no active content, no scripts, no external references. A gateway converting source-EMR note text (in OSCAR, effectively plain text with newlines) must sanitize and wrap it, not pass it through.

Relationship to ClinicalImpression

NexusEmrCoreClinicalImpression models the Assessment ("A") of a SOAP note as its own resource. A note carrying an assessment section and a ClinicalImpression therefore has two homes for the same text. The IG does not yet rule which is authoritative -- flagged as open.

Divergence from US Core

US Core models clinical notes as DocumentReference. This IG models authored notes as Composition and reserves DocumentReference for attached binary documents.

The divergence is intentional. FHIR's document architecture (and its C-CDA lineage) is the deeper prior art for authored, sectioned, attested narrative, and Composition.status expresses the note lifecycle natively -- indeed DocumentReference.docStatus borrows the CompositionStatus value set, so Composition is that lifecycle's native home. Implementers arriving from a US Core background should expect to find progress notes here, not on DocumentReference.

See Also

Terminology bindings

Path Strength Value set
Composition.status required composition-status
Composition.type extensible Composition Classification Value Set
Composition.category preferred Composition Kind Value Set
Composition.section.code extensible Composition Section Value Set