DocumentReference

  • Profile status: Draft
  • Canonical URL: http://fhir.smart4health.eu/StructureDefinition/s4h-documentreference

Use of resource in Smart4Health

DocumentReference is used to communicate a document along with associated meta-data (document type, author etc.). In this context, "document" can refer to a wide array of data types: text files, images (which may themselves be scans of paper documents) etc. Accordingly, the associated data can be in a number of formats e.g. PDF or JPEG. Currently, only the following file types are supported for Smart4Health: JPEG, PNG, TIFF, PDF, and DCM (Dicom images).

The data representing the data itself can be included directly in base-64 encoding (in DocumentReference.content.attachment.data) or referenced by a URL at which the data can be retrieved (in DocumentReference.content.attachment.url). In the Smart4Health context, inlining the data should be preferred as it ensures that the data is always available to the data consumer and avoids problems associated with data retrieval (access restrictions, internet connectivity, moved resource etc.). However, note that the Smart4Health platform limits the size of attachments to 10 MB.

Relation to other DocumentReference profiles

The IPS implementation guide does not contain a DocumentReference profile. In designing the Smart4Health profile, we have therefore tried to align with the DocumentReference profile from the Trillium II project, a project that was closely aligned with the IPS.

Guidelines for handling multiple files/attachment

In the base FHIR specification, DocumentReference resources are allowed to contain multiple content elements which, however, must represent the same content in different formats (e.g. the same document as a PDF and as plain text file). However, the exact interpretation of this latter requirement has proven complicated, leaving a risk of incorrect usage. To preempt such issues, the Smart4Health DocumentReference profile limits the number of content elements to exactly one, i.e. each such resource can carry exactly one binary attachment/file.

In cases where the source systems has multiple files grouped together, one should proceed as follows:

  • If the files contain distinct, complete documents: In this case, one DocumentReference resource should be created per file.
  • If the files contains copies of the same, complete document in different formats (e.g. PDF and plain text): In this case, one format should be chosen and a single DocumentReference resource containing the corresponding data created.
  • If the files contains different parts (e.g. separate pages) of the same document: In this case, the files must be merged together into one file that correctly represents the full document and then put in a single DocumentReference resource. It is not allowed to put the separate parts in different resources even if these are linked via DocumentReference.relatesTo.

Mandatory and must-support data elements

A valid instance according to this profile must satisfy the following constraints:

  • have a status (element: status) - base constraint
  • have the time the included document was created (element: date) - Smart4Health constraint, to allow proper identification of the resource within a complete patient record
  • have exactly one content element (element: content) containing an attachment conforming to the Smart4Health Attachment profile - Smart4Health constraint, to avoid confusion or incorrect use since the use and meaning of multiple content element is currently unclear

In addition, 12 top-level elements are marked as must-support.

Example resources

Formal views of profile content

Differential view

Shows only differences relative to the base resource definition.

idΣ0..1string
metaΣ0..1Meta
implicitRulesΣ ?!0..1uri
language0..1codeBinding
text0..1Narrative
contained0..*Resource
extensionI0..*Extension
modifierExtension?! I0..*Extension
masterIdentifierΣ0..1Identifier
identifierS Σ0..*Identifier
statusS Σ ?!1..1codeBinding
docStatusΣ0..1codeBinding
typeS Σ0..1Codeable Concept (IPS)Binding
categoryS Σ0..*Codeable Concept (IPS)
subjectS Σ I0..1Reference(Group | Device | S4hPatient | Practitioner (IPS))
dateS Σ1..1instant
authorS Σ I0..*Reference(Device | RelatedPerson | Practitioner (IPS) | PractitionerRole (IPS) | S4hPatient | Organization (IPS))
authenticatorI0..1Reference(Practitioner | PractitionerRole | Organization)
custodianS I0..1Reference(Organization (IPS))
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
codeΣ1..1codeBinding
targetΣ I1..1Reference(S4hDocumentReference)
descriptionS Σ0..1string
securityLabelΣ0..*CodeableConceptBinding
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
attachmentS Σ I1..1S4hAttachment
formatΣ0..1CodingBinding
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
encounterS I0..*Reference(EpisodeOfCare | S4hEncounter)
event0..*CodeableConcept
periodΣ I0..1Period
facilityType0..1CodeableConcept
practiceSetting0..1CodeableConcept
sourcePatientInfoI0..1Reference(Patient)
relatedI0..*Reference(Resource)

Snapshot view

Shows all constraints, including those from underlying profiles and the base resource definition.

idΣ0..1string
metaΣ0..1Meta
implicitRulesΣ ?!0..1uri
language0..1codeBinding
text0..1Narrative
contained0..*Resource
extensionI0..*Extension
modifierExtension?! I0..*Extension
masterIdentifierΣ0..1Identifier
identifierS Σ0..*Identifier
statusS Σ ?!1..1codeBinding
docStatusΣ0..1codeBinding
typeS Σ0..1Codeable Concept (IPS)Binding
categoryS Σ0..*Codeable Concept (IPS)
subjectS Σ I0..1Reference(Group | Device | S4hPatient | Practitioner (IPS))
dateS Σ1..1instant
authorS Σ I0..*Reference(Device | RelatedPerson | Practitioner (IPS) | PractitionerRole (IPS) | S4hPatient | Organization (IPS))
authenticatorI0..1Reference(Practitioner | PractitionerRole | Organization)
custodianS I0..1Reference(Organization (IPS))
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
codeΣ1..1codeBinding
targetΣ I1..1Reference(S4hDocumentReference)
descriptionS Σ0..1string
securityLabelΣ0..*CodeableConceptBinding
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
attachmentS Σ I1..1S4hAttachment
formatΣ0..1CodingBinding
id0..1string
extensionI0..*Extension
modifierExtensionΣ ?! I0..*Extension
encounterS I0..*Reference(EpisodeOfCare | S4hEncounter)
event0..*CodeableConcept
periodΣ I0..1Period
facilityType0..1CodeableConcept
practiceSetting0..1CodeableConcept
sourcePatientInfoI0..1Reference(Patient)
relatedI0..*Reference(Resource)