Skip to content

DocumentReference Profile

Canonicalhttps://fhir.apps.health/StructureDefinition/nexus-emr-core-documentreference
Statusdraft · 1.33.0
BaseDocumentReference (constraint)
CQL primary code pathtype — what this means
SourceFSH · 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.

Overview

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.

A received document uploaded or scanned into the inbox or chart, including a fax or mailed paper, lands here today; a report received over HRM is written as a DiagnosticReport. Which resource a received report should become is not yet settled, so a reader should expect one on either. See Incoming reports.

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

Handbook: Incoming Reports

Where a received report lands, who it was sent to, how it arrived, and who is responsible for acting on it.

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 (|true) in meta.tag and are never offered for deletion -- the software reasserts them, so a deletion is undone at the next reconciliation. Nexus EMR writes that tag today at https://fhir.apps.health/tags/document-reference/readonly, a pre-migration address; see the code system for the migration note and match both addresses when reading. 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.

Documents awaiting a patient match

Incoming paper and faxes are often uploaded before anyone knows whose they are. Such a document is the second kind with no subject: it carries the awaiting-patient tag under CodeSystem/nexus-filing-state in meta.tag, is on no patient's chart, and waits in the inbox until someone matches it. Filing it sets subject and removes the tag in the same write; a document never carries both. A bare missing subject is not enough: without the tag, a subject-less document that is not a form template is malformed.

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

A subject is required except in three marked cases. nexus-documentreference-subject-unless-template (severity error) requires a subject unless the document is a form template (an identifier under NamingSystem/nexus-form-template), carries the awaiting-patient tag, or is the terms and conditions (an identifier under NamingSystem/nexus-terms-and-conditions), and nexus-awaiting-patient-has-no-subject (severity error) rejects a document that carries both the tag and a subject. The form-template and terms-and-conditions identifiers are the only identifiers any invariant on this profile reads; 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.

See Also

Terminology bindings

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