DocumentReference Profile¶

Canonical	`https://fhir.apps.health/StructureDefinition/nexus-emr-core-documentreference`
Status	draft · 1.25.1
Base	DocumentReference (constraint)
CQL primary code path	`type` — what this means
Source	FSH · JSON

Nexus EMR profile for an ATTACHED DOCUMENT -- a clinical document that exists as a file: scanned paper, incoming faxes, external consult letters received as PDF, signed consent forms, patient-uploaded files. FHIR holds the metadata and clinical context; the bytes live in document storage and are reached through content.attachment.url.

Use NexusEmrCoreComposition instead for notes AUTHORED in this EMR -- encounter notes, consult notes, telephone notes -- where the narrative is text the EMR controls and belongs in FHIR as XHTML. The two profiles partition the clinical-document space; neither is a fallback for the other.

Documents are submitted with inline base64 in content.attachment.data; the gateway stores them and rewrites the attachment to carry a url instead. See the content element definitions for the full round-trip contract, including what a reader should expect back.

Aligned with CA-Core+ standards and CII requirements for Canadian healthcare.

Overview

NexusEmrCoreDocumentReference is the metadata wrapper for an attached document -- a clinical document that exists as a file: scanned paper, an incoming fax, an external consult letter received as PDF, a signed consent form, a patient-uploaded file. FHIR holds the indexing, discovery and clinical context; the bytes live in document storage and are reached through content.attachment.url.

Scope narrowed 2026-08-06

This profile used to cover clinical documents in general, and the OSCAR FHIR Gateway consequently mapped textual encounter notes onto it. It no longer does. Notes authored in this EMR are now NexusEmrCoreComposition, where the narrative lives in FHIR as XHTML and Composition.status carries the draft/signed/amended lifecycle.

Composition or DocumentReference?

	`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

The test is not "is it clinical" -- both are. It is did we write it, and is the content text we control? A consult note received as a PDF is a DocumentReference; a consult note typed here is a Composition. The distinction is the form the content arrives in, not the clinical genre.

Content: the round trip

What a writer sends is not what a reader gets back. The gateway converts inline content into stored files on the way in.

Writing. Submit the document inline -- contentType plus base64 in attachment.data, with no url. On create or update the gateway stores the bytes and rewrites the attachment before persisting: url is set to the stored-document address, size and hash (SHA-1) are computed, and data is cleared. Writers should not compute size, hash, or url themselves.

Reading. Expect url and no data. Consumers must not assume data is populated, and must not read its absence as an empty document.

Do not send data and url together

The conversion is guarded on url being absent. An attachment carrying both bypasses storage entirely, and the base64 is persisted inline in the FHIR resource where it will be echoed on every subsequent read. Send data to upload new content, or url alone to reference something already stored -- never both.

URL shape. An absolute URL served by the platform's File Storage Service:

https://{host}/fss/api/v1/file/{documentId}

This is not a FHIR Binary reference (this platform implements no Binary endpoint), and not a pre-signed or SAS blob URL. It is a normal API endpoint.

Fetching it. The URL is not self-authorizing. Retrieval requires the caller's own bearer token with file-read permission, and resolves within the caller's tenant -- another tenant's document is not found regardless of the identifier. A client treating this as a public or signed download link gets a 401, not a document. Reads are audited.

Stability. The URL is permanent for the life of the document -- no expiry, no rotation -- and survives updates to the DocumentReference, because the gateway reuses the stored-document identity. It may safely be cached and stored.

Supplying a URL yourself is permitted, for content the platform already holds, but the host is validated: an untrusted host is rejected with a 400 and an OperationOutcome directing you to upload via data instead. Do not point this element at arbitrary external systems -- external content should be ingested, not linked.

Document status

status is current / superseded / entered-in-error, tracking the reference record. Updates create a new DocumentReference and mark the previous one superseded, which keeps document history immutable and avoids version chaining.

Note this differs from the authored-note model: a Composition is amended in place with version history. Documents are files and are replaced; notes are text and are edited.

Form templates

A form template is the tenant-wide blank of a fillable form: a DocumentReference with no subject, marked by an identifier under NamingSystem/nexus-form-template whose value is the form type's slug (wsib-form-8), the same slug every form filled from it carries under nexus-form. System-provisioned templates carry the readonly tag (https://fhir.apps.health/tags/document-reference/readonly|true) and are never offered for deletion. A template may carry the Form Template Field Mapping extension: which of the file's fillable fields a chart value pre-fills when a form is started from it. Only a template may carry it; a filed form holds the filled values in its own file.

Identifiers

identifier is 0..* and no canonical system is mandated. Carry the identifier the source system assigns, under a system URI that genuinely identifies it. Where a local code has no recognized system, the raw-code fallback template applies: https://fhir.apps.health/NamingSystem/<instance-id>-documentreference-raw-code.

Invariants

No invariant on this profile checks identifiers. documentreference-has-raw-identifier (severity warning) was removed in 1.21.0 along with its 33 siblings, and the instance-scoped identifier pattern it recommended is retired.

Document Categorization

Use category (not type) for classification. Multiple categories can be assigned:

Category	LOINC Code	Use Case
Consultation Note	11488-4	Specialist consultation received as a file
Discharge Summary	18842-5	Hospital discharge document from another institution
Laboratory Report	11502-2	Lab results delivered as PDF rather than as DiagnosticReport
Referral Note	57133-1	Referral letters

Since the 2026-08-06 narrowing, a Progress Note (11506-3) authored in this EMR is a Composition, not a DocumentReference. The codes above remain valid here for documents that arrived carrying them.

MIME types

contentType is required and must accurately describe the bytes. Common values:

application/pdf - most common for clinical documents
image/jpeg, image/png, image/tiff - scanned documents
application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document - Word
text/plain, text/html - simple or formatted text documents

No server-side allow-list is enforced -- contentType is stored and echoed verbatim, so an inaccurate value propagates to every consumer. The chart's document viewer previews only a safe subset (PDF, plain text, and common image formats) and offers download for anything else.

Terminology bindings

Path	Strength	Value set
`DocumentReference.type`	extensible	c80-doc-typecodes