DocumentReference Profile¶
| Canonical | ../StructureDefinition/nexus-emr-core-documentreference |
|---|---|
| Status | draft · 1.26.0 |
| 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.
TypedFhir API / Pydantic schema
The typed accessor surface DocumentReference exposes for DocumentReference — generated from this IG's compiled profile; each typed accessor has a validating raw-FHIR twin (xRaw) where marked. The three ports are parity-enforced.
The AI-facing shape: from typed_fhir.facade.generated.schemas import DocumentReferenceSchema — model_json_schema() is a structured-output / tool definition; instantiating validates an extraction. Generated source.
class DocumentReferenceSchema(BaseModel):
"""AI-facing shape of the DocumentReference profile: the facade's typed accessor
surface (curated + salient fields) as a pydantic model. `model_json_schema()` is a
structured-output / tool schema; instantiating validates an extraction."""
model_config = ConfigDict(extra="forbid")
status: Literal["current", "entered-in-error", "superseded"] | None = Field(
None,
description=(
"Where the document reference is in its lifecycle. The status of this document "
"reference. Allowed values: - current: The document is active and current - "
"superseded: The document has been replaced by a newer version - entered-in-error: "
"The document was created in error and should not be used (deleted) When a document "
"is updated, the previous version can be marked as 'superseded' and a new "
"DocumentReference created with status 'current'. This approach: - Maintains "
"immutable document history - Provides clear version tracking - Enables audit trails "
"- Supports document lifecycle management. Note: This is the status of the "
"DocumentReference object, which might be independent from the docStatus element. "
"This element is labeled as a modifier because the status contains the codes that "
"mark the document or reference as not currently valid. DocumentReference.status — "
"1..1"
),
)
doc_status: Literal["amended", "entered-in-error", "final", "preliminary"] | None = Field(
None,
description=(
"preliminary | final | amended | entered-in-error. The status of the underlying "
"document. Note: The document that is pointed to might be in various lifecycle "
"states. DocumentReference.docStatus — 0..1"
),
)
type: Concept | None = Field(
None,
description=(
"Precise type of document (use category instead). Specifies the precise type of "
"clinical document referenced (e.g., specific LOINC code for document type). While "
"this field is supported for backward compatibility with systems expecting it, Nexus "
"EMR strongly recommends using 'category' instead because: - Category supports "
"multiple classifications per document - Category allows both clinical and "
"administrative taxonomies - Type is limited to a single classification If used, "
"prefer LOINC codes for interoperability. Where this code was mapped from a source "
"system's own vocabulary, carry the raw coding alongside the mapped one, flagged "
"`userSelected = true`. See [Carrying the raw "
"code](../guide/patterns/raw-codes.md). Note: Key metadata "
"element describing the document that describes he exact type of document. Helps "
"humans to assess whether the document is of interest when viewing a list of "
"documents. DocumentReference.type — 0..1. codes (extensible): 11206-0 | 11485-0 | "
"11486-8 | 11488-4 | 11490-0 | 11492-6 | 11494-2 | 11495-9 | …"
),
)
category: Concept | None = Field(
None,
description=(
"Document categorization (preferred over type). High-level categorization of the "
"document. This is the PREFERRED method for document classification in Nexus EMR. "
"Multiple categories can be assigned to provide different perspectives on the "
"document's purpose and content. Common categories include: - Received correspondence "
"(consult letters, discharge summaries from other institutions) - Scanned paper and "
"incoming faxes - Diagnostic documents (lab or imaging reports delivered as files "
"rather than as DiagnosticReport) - Legal and administrative documents (consent "
"forms, advance directives, insurance forms) - Patient-supplied documents Note what "
"is NOT here since the 2026-08-06 narrowing: progress notes and consultation notes "
"AUTHORED in this EMR are `NexusEmrCoreComposition`, not DocumentReference. A consult "
"note *received* as a PDF is still a DocumentReference -- the distinction is the form "
"the content arrives in, not the clinical genre. Use standard terminologies (LOINC, "
"SNOMED CT) for maximum interoperability. Note: Key metadata element describing the "
"the category or classification of the document. This is a broader perspective that "
"groups similar documents based on how they would be used. This is a primary key used "
"in searching. DocumentReference.category — 0..*"
),
)
subject: Reference | None = Field(
None,
description=(
"The patient the document is about. The patient that this document pertains to. "
"Required for every document EXCEPT a form template, which is the tenant-wide blank "
"of a form type and is about no patient; the "
"`nexus-documentreference-subject-unless-template` invariant states that rule in "
"evaluable form. When present it must reference a valid NexusEmrCorePatient resource, "
"and the reference should use the patient's identifier for reliable cross-system "
"identification. While the FHIR standard allows documents about other subjects "
"(Device, Practitioner, Group), Nexus EMR currently only supports patient-centric "
"documents to align with Canadian healthcare requirements. Note: Required unless this "
"is a form template. DocumentReference.subject — 0..1"
),
)
date: FuzzyDate | None = Field(
None,
description=(
"When DocumentReference was created (not document date). When this DocumentReference "
"resource was created in the system. This is NOT necessarily when the document itself "
"was created or when the documented service occurred. Timing relationships: - date: "
"When DocumentReference was created (this field) - content.attachment.creation: When "
"document was created - context.period: When clinical service occurred Example: A "
"discharge summary for April 10-15 admission might be: - Service period: 2025-04-10 "
"to 2025-04-15 - Document created: 2025-04-15T14:00:00 - DocumentReference created: "
"2025-04-16T09:00:00 (next day upload) This field is primarily for technical/audit "
"purposes. Note: Referencing/indexing time is used for tracking, organizing versions "
"and searching. DocumentReference.date — 0..1"
),
)
author: Reference | None = Field(
None,
description=(
"Who wrote the document. Identifies who was responsible for writing the document "
"content. Can include multiple authors for collaborative documents. Note the "
"distinction: - Author: Who wrote/created the content - Authenticator: Who legally "
"verified/signed the document - Custodian: Organization maintaining the document - in "
"EMRs, you probably want to be using 'authenticator' rather than 'author' here. - eg: "
"'author' may be a medical student, 'authenticator' could be the doc signing off. - "
"'authenticator' is the person who is medically responsible for the content of this "
"document. Authors can only be EMR users in this context, referenced as a "
"**Practitioner** (the primary provider identity in this IG) or as a "
"**PractitionerRole** where the clinic/role binding is part of the assertion. Order "
"matters - list primary author first. Note: Not necessarily who did the actual data "
"entry (i.e. typist) or who was the source (informant). DocumentReference.author — "
"0..*"
),
)
authenticator: Reference | None = Field(
None,
description=(
"Practitioner who verified this document. The practitioner who has legally "
"authenticated or verified this document, taking responsibility for its content. This "
"represents medical/legal responsibility rather than authorship. The authenticator: - "
"Must have appropriate authority/credentials - Takes responsibility for document "
"accuracy - May or may not be the document author - Should be a single practitioner "
"(not multiple) Typically the attending physician, consultant, or supervising "
"practitioner. References a **Practitioner** -- the primary provider identity in this "
"IG. A **PractitionerRole** reference is also permitted, for the cases where the "
"clinic/role binding is part of what is being asserted (e.g. authentication performed "
"in a specific role at a specific organization, which Practitioner cannot express "
"since it has no `organization`). Note: Represents a participant within the author "
"institution who has legally authenticated or attested the document. Legal "
"authentication implies that a document has been signed manually or electronically by "
"the legal Authenticator. DocumentReference.authenticator — 0..1"
),
)
custodian: Reference | None = Field(
None,
description=(
"Organization responsible for document maintenance. The organization that is "
"responsible for maintaining the authoritative source of this document and "
"controlling access to it. This is a REQUIRED field that identifies: - Who has "
"stewardship of the document - Where to direct queries about the document - Who is "
"responsible for retention policies - Who manages access permissions Typically the "
"organization that created the document or currently manages the patient's care. Must "
"reference a valid NexusEmrCoreOrganization resource. Note: Identifies the logical "
"organization (software system, vendor, or department) to go to find the current "
"version, where to report issues, etc. This is different from the physical location "
"(URL, disk drive, or server) of the document, which is the technical location of the "
"document, which host may be delegated to the management of some other organization. "
"DocumentReference.custodian — 1..1"
),
)
description: str | None = Field(
None,
description=(
"Human-readable description of document content. A human-readable description of the "
"document's content and purpose. While optional, this field is strongly recommended "
"as it: - Provides quick context without opening the document - Improves "
"searchability and discoverability - Helps users identify relevant documents quickly "
"- Supports accessibility requirements Should be concise but informative (typically "
"1-2 sentences). Examples: - \"Complete blood count showing mild anemia, hemoglobin "
"10.2\" - \"Cardiology consultation for chest pain, recommending stress test\" - "
"\"Discharge summary following 5-day admission for pneumonia\". Note: What the document "
"is about, a terse summary of the document. DocumentReference.description — 0..1"
),
)
security_label: Concept | None = Field(
None,
description=(
"Document security-tags. A set of Security-Tag codes specifying the level of "
"privacy/security of the Document. Note that DocumentReference.meta.security contains "
"the security labels of the \"reference\" to the document, while "
"DocumentReference.securityLabel contains a snapshot of the security labels on the "
"document the reference refers to. Note: The confidentiality codes can carry multiple "
"vocabulary items. HL7 has developed an understanding of security and privacy tags "
"that might be desirable in a Document Sharing environment, called HL7 Healthcare "
"Privacy and Security Classification System (HCS). The following specification is "
"recommended but not mandated, as the vocabulary bindings are an administrative "
"domain responsibility. The use of this method is up to the policy domain such as the "
"XDS Affinity Domain or other Trust Domain where all parties including sender and "
"recipients are trusted to appropriately tag and enforce. In the HL7 Healthcare "
"Privacy and Security Classification (HCS) there are code systems specific to "
"Confidentiality, Sensitivity, Integrity, and Handling Caveats. Some values would "
"come from a local vocabulary as they are related to workflow roles and special "
"projects. DocumentReference.securityLabel — 0..*"
),
)
content: dict | None = Field(
None,
description=(
"Document attachment(s) -- submitted inline, stored as files, read back by URL. The "
"document content and its metadata. Each content element is one attachment. Multiple "
"attachments per DocumentReference are supported (a referral letter plus supporting "
"results), but most cases are a single document. THE ROUND TRIP -- what a writer "
"sends is not what a reader gets back. WRITING. Submit the document inline: "
"`contentType` plus base64 in `attachment.data`, with no `url`. On create or update "
"the gateway stores the bytes, then rewrites the attachment before persisting it: "
"`url` is set to the stored-document address, `size` and `hash` (SHA-1) are computed "
"and filled in, and `data` is cleared. Writers SHOULD NOT compute `size`, `hash`, or "
"`url` themselves. READING. Expect `url` and no `data`. Fetch the bytes from the URL "
"(see `content.attachment.url` for the auth contract). Consumers MUST NOT assume "
"`data` is populated. SENDING BOTH IS A TRAP. The conversion is guarded on `url` "
"being absent. An attachment carrying BOTH `data` and a `url` bypasses storage "
"entirely and the base64 is persisted inline in the FHIR resource, where it will be "
"echoed on every subsequent read. Send one or the other: `data` to upload new "
"content, `url` only to reference something already stored. STABLE URLS ACROSS "
"UPDATES. Updating a DocumentReference reuses the existing stored-document identity, "
"so the URL does not churn when metadata changes. (Note this is "
"DocumentReference-only behaviour; `DiagnosticReport.presentedForm` runs through the "
"same middleware but without the existing-document lookup, so its attachments get a "
"fresh URL on each update.) At least one of `data` or `url` MUST be present per "
"attachment (invariant `attachment-has-data-or-url`) -- which, given the above, means "
"\"inline on the way in, URL on the way out.\". DocumentReference.content — 1..*"
),
)
title: str | None = Field(
None,
description=(
"Document title for display. Human-readable title for the document. While optional, "
"this field is strongly recommended for user experience. The title should be: - "
"Descriptive and meaningful - Suitable for display in document lists - Include "
"relevant context (e.g., date, type) - 50-100 characters typically Examples: - "
"\"Discharge Summary - April 15, 2025\" - \"CBC Results - Hemoglobin 10.2\" - \"Cardiology "
"Referral - Dr. Smith\" - \"Chest X-Ray Report - Normal\". Salient field — "
"content.first().attachment.title"
),
)
url: str | None = Field(
None,
description=(
"Absolute URL to the stored document -- the READ channel; set by the gateway. Where "
"the document bytes can be fetched. This is the read channel, and for "
"gateway-ingested documents it is written BY the gateway during storage -- clients "
"uploading new content should leave it empty and send `data`. 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 credentials: a bearer token carrying the "
"file-read permission, and the request resolves within the caller's tenant -- a "
"document belonging to another tenant is not found, regardless of the identifier. A "
"client that treats this like a public or signed download link will get 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 "
"(the gateway reuses the stored-document identity). It may therefore be cached and "
"stored. SUPPLYING A URL YOURSELF. Permitted, for referencing content already held by "
"the platform, but validated: the host must be trusted, and 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 -- content that "
"lives outside the platform should be ingested, not linked. Note: If both data and "
"url are provided, the url SHALL point to the same content as the data contains. Urls "
"may be relative references or may reference transient locations such as a wrapping "
"envelope using cid: though this has ramifications for using signatures. Relative "
"URLs are interpreted relative to the service url, like a resource reference, rather "
"than relative to the resource itself. If a URL is provided, it SHALL resolve to "
"actual data. Salient field — content.first().attachment.url"
),
)