The FHIR DocumentReference resource

In the previous FHIR-XDS post we discussed how a document source actor (ie a system that creates a document) could create a document and DocumentReference resource and send them to the Repository server. (Actually, we described a couple of ways that this could be done – and there are a few subtleties yet to discuss about server behaviour – but we’ll hold that for later).

However, we didn’t have a lot of time to talk about the DocumentReference resource itself. This resource represents the metadata about the document and allows a consumer to search the registry (or any server hosting these resources) to retrieve matching documents. From these results, a consumer can then generate a list of documents so that a consumer can select one to view.

The documents themselves can be of any allowed type (CDA, PDF, FHIR document, text etc) and can be stored on any server accessible via HTTP – and they do not need to be FHIR servers. It is quite legitimate for a DocumentReference resource to refer to a static document on any server (or, for that matter, a URL that generates a document ‘on the fly’, though you’d want some way to persist the generated document for medico-legal reasons as described in the ‘IHE on-demand document‘ profile). And, if one is being particularly pedantic, then even HTTP is not really required – you could use FTP or any other supported protocol.

It is important to note that although the DocumentReference resource was developed to support some of the requirements of an XDS infrastructure, it is not restricted to that purpose and can be used in any situation where the business requirement is to create a ‘list of available documents’, from which one or more can be chosen for viewing.

In fact, the FHIR specification defines a specific XDS profile that describes how the DocumentReference resource is to be used in the context of an XDS installation – for example some fields that are optional in the resource, are required when acting as a proxy to XDS. The link also gives guidance for mapping between XDS and FHIR elements, including fields required for XDS that are not in the DocumentReference and so represented by extensions.

The following description refers to the generic DocumentReference resource. Note that there are a number of properties whose value should come from a ValueSet defined by the governance body that oversees the overall installation (an Affinity Domain in XDS-speak – though the affinity domain covers much more than just code sets). We will talk a bit more about ValueSet’s after this list.

  • The masterIdentifier is the identifier of the document as created by the source. It is version specific – i.e. a new one is required if the document is updated (We’ll talk about updating documents in a separate post).
  • There can be any number of other document identifiers that make sense. For example, there might be a version independent identifier here.
  • The subject is who the document is about. Generally this is a patient, but the specification also supports a Practitioner, a Group or a Device.
  • The type and class indicate what kind of document this is- (eg a discharge summary). A ValueSet should be defined for each. (Note that ‘class’ has been called ‘sub-type’ in some versions of this resource)
  • There is at least one author, which is a Practitioner.
  • There can be an Organization which is the custodian of the document – responsible for maintaining the document
  • There’s a policyManager link to a URL that describes the access policies to the document.
  • The authenticator of the document can be an Organization or a Practitioner.
  • The created date is when the document was created (not necessarily related to the period of the service that the document may describe – this is in the context.period element).
  • The indexed date which is when the DocumentReference resource was created.
  • The status allows minimal workflow of this DocumentReference resource (NOT the underlying document). Options are current, superseded or error. We’ll talk more about this status when we talk about updating a document in a later post.
  • The docStatus and supercedes allow a document to be updated (superseded) or otherwise have it’s status changed. This is a CodeableConcept, and so can accommodate a specific workflow defined by the affinity domain such as preliminary, final, amended or whatever, as documented in the ValueSet.
  • The description is the title of the document. If you’re displaying list of documents then this would be a good property to use.
  • The Confidentiality property allows a privacy policy to control the access to a document. The policy can also use the generic tags functionality in FHIR.
  • The PrimaryLanguage element indicates exactly that – no surprises here. It is a code, and is bound to the IETF Language tag.
  • mimeType and format indicate how the document is represented – eg xml, pdf, msword etc.
  • Size allows a client to estimate download time of the document, and the hash can ensure integrity.
  • The Location is a URI that indicates from where the document can be downloaded. This does not need to be a FHIR server. The client will (generally) not know what this is when creating the resource as it will be related to the ID that the server assigns. However, either it or the service property is required, so it may be necessary to create a ‘dummy’ resource using the cid: prefix so the server knows it is not real – or define a service. You would define a local policy to describe this, which could be identified in the policyManager link above.
  • The service is used if the location is not known. You would use this if you weren’t using simple FHIR REST, so for the moment we’ll ignore it.
  • The context allows you to specify the clinical context of the document – at least the context that is useful in searching or displaying the document list. The period that the document refers to and the facility type are present, but you can add codes that make sense here as well.

For reference, the following fields need to have their options defined by the governing body using a ValueSet. These can either be defined directly in the ValueSet or be a sub-set of an external Terminology like LOINC or SNOMED.

  • type
  • subtype
  • docStatus
  • confidentiality
  • mimeType
  • format
  • context.code
  • context.facilityType

The recommended way to document this is to create a Profile resource that describes the implementation, and refers to the appropriate ValueSets – with the whole lot being saved in FHIR server/s so that they can be easily located. The option below shows a minimal profile that sets the ValueSet for the confidentiality property.

<Profile xmlns="">
         <status value="additional"/>
         <div xmlns="">Minimal profile for confidentiality codes in DocumentReference</div>
     <name value="Elbonian XDS Profile"/>
     <status value="draft"/>
         <type value="DocumentReference"/>
         <name value="XDSDocumentReference"/>
             <path value="DocumentReference.confidentiality"/>
             <name value="ConfidentialityOptions"/>

                 <short value="Confidentiality Code options"/>
                 <formal value="Confidentiality Code options"/>
                 <min value="1"/>
                 <max value="1"/>
                 <isModifier value="false"/>
                     <name value="List of confidentiality options"/>
                     <isExtensible value="false"/>
                     <referenceResource value="/ValueSet/ConfidentialityOptions"/>

and the ValueSet that it references could look like:

<ValueSet xmlns="">
         <status value="additional"/>
         <div xmlns="">The value set for confidentiality codes in the elbonian document sharing
         project. The codes are defined directly by the valueset, rather than references to an external terminology</div>
     <name value="ConfidentialityOptions"/>
     <description value="ConfidentialityOptions"/>
     <status value="draft"/>
     <!-- Define the  options in the resource rather than an external terminology-->
         <system value=""/>
             <code value='N'/>
             <display value="Normal"/>
             <definition value="That the document is of normal confidentiality - is able to be viewed for any authenticated user"/>
             <code value='H'/>
             <display value="High"/>
             <definition value="Then the document is Highly confidential - eg Mental health - and can only be viewed by people authorized to access documents at that level"/>

Finishing up…

In the previous post I promised that I would talk about the DocumentManifest resource. This is a new addition to the FHIR family, and has been introduced to support the ability for a document source to submit a collection of documents in a single batch as XDS does.

In truth, I’m not entirely clear how this resource should be used. It does have the recipient element, which provides the basis for a notification system, but beyond that the main value would seem to be that there can be more than a single document in a batch submission to the Repository server. I’ll update the post when I learn more.

So, we have saved a document in the repository and updated the registry. In the next post, we’ll switch our attention to the Document Consumer and discuss how to query the registry for documents, and to get the actual document itself.

About David Hay
I'm an independent contractor working with a number of Organizations in the health IT space. I'm an HL7 Fellow, Chair Emeritus of HL7 New Zealand and a co-chair of the FHIR Management Group. I have a keen interest in health IT, especially health interoperability with HL7 and the FHIR standard. I'm the author of a FHIR training and design tool - clinFHIR - which is sponsored by InterSystems Ltd.

13 Responses to The FHIR DocumentReference resource

  1. Friendly Fhir says:

    The metadata attributes listed are close to those available for XDS document entries, but I notice that facility and practice setting are missing. I rate these higher than an uncoded attribute like description/title and wonder whether there’s a case for their inclusion.

    • David Hay says:

      Certainly can be included as extensions (and I note that practiceSetting is present in the example of the XDS profile but not the profile itself – suggesting it is an oversight, and meant to be there)

      is ‘facilityType’ (context.facilityType) close enough for your needs? If not, then is the custodian a match?


  2. Friendly Fhir says:

    Thanks, that works.
    The value sets available for metadata attributes do not make a wonderful selection from what I can see. Or perhaps there’s too much selection. I notice that FHIR tends to mix and match among code sets.
    I would like to use LOINC code to indicate the document type/subtype (not sure which) and some combination of LOINC axes Kind of Document (eg Report), Type of Service (eg Consultation), Setting (eg Hospital) and Subject Matter Domain (eg Interventional cardiology) in other metadata attributes. Would you recommend that?

  3. Pingback: Getting documents from a #FHIR XDS infrastructure | Hay on FHIR

  4. David Hay says:

    renamed ‘sub-type’ to ‘class’

  5. prasad says:

    Thanks for the very information blog on DocumentReference. I am looking for ways to represent unstrutcured documents (candidates for NLP) using DocumentReference. Could you provide some insights on how could one identify candidates/documents for NLP ? Looks like DocumentReference could be used for representing both structured and unstructured documents.

    • David Hay says:

      Hi Prasad. Do you mean can you store an unstructured document in a DocumentReference? Sure – content.attachment can have a blob in its data element – or you could store the unstructured document in the /binary end point ( )

      In addition, DR.content is a 1:* so I guess it could reference both a binary and a structure resource from a binary – though I suspect any resources extracted from a document will be multiple – perhaps you could represent the ‘extracted’ data as a FHIR document, then use DR.relatesTo to relate the documents. If you proceed down this path, then it would be a good topic for the FHIR chat (


  6. Etienne says:

    Hi ! I’m wondering what would be the Bundle.type of a Bundle with an embedded DocumentReference. I’m looking for a way to properly send non-FHIR documents and I was considering using a DocumentReference resource inside a Bundle as described in your previous blog post. The thing is the “document” bundle type mentions that “The bundle is a document. The first resource is a Composition.” and Compositions are for FHIR documents from what I understand.
    Another question : why not including the non-FHIR document in the DocumentReference.content.attachment, instead of as a separate Binary resource ?

    Thanks for your insights !

    • David Hay says:

      Hi Etienne,

      You can certainly have the unstructured document as a b64 encoded blob in the DR.content.attachment. If you do though, it will be returned in a query on DR – which may have bandwidth considerations. wrt including a DR inside a bundle, the DR.type would depend on the ‘paradigm’ being used to move the bundle around. For example, if you were ‘messaging’ the bundle, then it would be a message. If using REST then likely a ‘transaction’ and so forth.


      • Etienne says:

        Hi David,

        The DocumentReference.type and the Bundle.type are of different kind. I suppose you were refering to the latter when you talked about ‘message’ and ‘transaction’ ! 🙂
        For the moment, we only plan to send the XML file containing the Bundle via FTP like we do with CDAR2 XML files. So I suppose the best choice would be the ‘message’ BundleType for this purpose. Do you agree ?

  7. David Hay says:

    Indeed – a slip of the keyboard! Interesting question about FTP – and one worth bringing up on the FHIR chat. I would think that this would simply be a ‘collection’ – though I guess it depends on what you expect the recipient to do with it. If you are working in a messaging paradigm then you’d need to include a MessageHeader resource in the bundle as well and I’m not sure that you need that…

    • Etienne says:

      Okay thanks ! Then how could I add a reference to the software used to produce the document attached to the DocumentReference ? I’ve got codes for dozens of different softwares in our global health system. I was thinking about an author of type Device, but there’s only a hint about this possibility in the documentation tooltip of the Device.version.

      • David Hay says: seems a reasonable choice – you can have many authors…

Leave a Reply

%d bloggers like this: