This page is part of the FHIR Specification (v0.5.0: DSTU 2 Ballot 2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

6.1 Resource List - Content

This resource maintained by the FHIR Management Group Work Group

A set of information summarized from a list of other resources.

6.1.1 Scope and Usage

The List resource is a flat, possibly ordered, collection of records. List resources are used in many places, including allergies, medications, alerts, family history, medical history, etc. List resources can be used to support patient-specific clinical lists as well as lists that manage workflows such as tracking patients, managing teaching cases, etc. Resources supported by the List resource can be homogenous – consisting of only one type of resource (e.g. allergy list) as well as heterogeneous – containing a variety of resources (e.g. a problem list including Conditions, AllergyIntolerances, recent Procedures, etc.).

Lists will typically include references to the resources that make up the list, however in some cases the details of the content of the List might be expressed in narrative only. E.g. A text record of a family history. The List resource is only needed if there is a need to filter the set of resources by a mechanism that cannot be accomplished via a simple query. I.e. There is no need to have a List for all AllergyIntolerances that exist on a server for a given Patient. However, List is an appropriate mechanism to provide a filtered list of the subset of AllergyIntolerances that are deemed to be "current".

6.1.2 Boundaries and Relationships

There are five mechanisms in FHIR for communicating collections of resources:

This List resource - enumerates a flat collection of resources and provides features for managing the collection. While a particular List instance may represent a "snapshot", from a business process perspective the notion of "List" is dynamic – items are added and removed over time. The list resource references other resources. Lists are may be curated and have specific business meaning.
The Group resource - defines a group of specific people, animals, devices, etc. by enumerating them, or by describing qualities that group members have. The group resource refers to other resources, possibly implicitly. Groups are intended to be acted upon or observed as a whole. E.g. performing therapy on a group, calculating risk for a group, etc. This resource will commonly be used for public health (e.g. describing an at-risk population), clinical trials (e.g. defining a test subject pool) and similar purposes.
The Composition resource – defines a set of healthcare-related information that is assembled together into a single logical document that provides a single coherent statement of meaning, establishes its own context and that has clinical attestation with regard to who is making the statement. The composition resource provides the basic structure of a FHIR document. The full content of the document is expressed using a bundle. Compositions will often reference Lists as the focus of particular sections.
The Bundle resource is an infrastructure container for a group of resources. It does not have narrative and is used to group collections of resources for transmission, persistence or processing (e.g. messages, documents, transactions, query responses, etc.) The content of bundles is typically algorithmically determined for a particular exchange or persistence purpose.
The DomainResource.contained element allows multiple resources to be nested inside any DomainResource. This is a special type of grouping where the grouped resources lose independent existence - they no longer have their own identifiers, can't easily be queried independently, etc. Use of this grouping is a technical mechanism for managing the independence of resources and has no impact on meaning. Contained, bundles and remotely referenced resources convey the same meaning.

This resource is referenced by [Composition]

Structure

Name	Flags	Card.	Type	Description & Constraints
List	I		DomainResource	Information summarized from a list of other resources The deleted flag can only be used if the mode of the list is "changes" A list can only have an emptyReason if it is empty
identifier		0..*	Identifier	Business identifier
title	Σ	0..1	string	Descriptive name for the list
code	Σ	0..1	CodeableConcept	What the purpose of this list is ListPurpose (Example)
subject	Σ	0..1	Patient \| Group \| Device \| Location	If all resources have the same subject
source	Σ	0..1	Practitioner \| Patient \| Device	Who and/or what defined the list contents
status	?! Σ	1..1	code	current \| retired \| entered-in-error ListStatus (Required)
date	Σ	0..1	dateTime	When the list was prepared
orderedBy		0..1	CodeableConcept	What order the list has ListOrder (Preferred)
mode	?! Σ	1..1	code	working \| snapshot \| changes ListMode (Required)
note		0..1	string	Comments about the note
entry	I	0..*	Element	Entries in the list
flag		0..*	CodeableConcept	Workflow information about this item ListItemFlag (Example)
deleted	?! I	0..1	boolean	If this item is actually marked as deleted
date		0..1	dateTime	When item added to list
item		1..1	Any	Actual entry
emptyReason	I	0..1	CodeableConcept	Why list is empty ListEmptyReason (Preferred)

UML Diagram

XML Template

<List xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Business identifier --></identifier>
 <title value="[string]"/><!-- 0..1 Descriptive name for the list -->
 <code><!-- 0..1 CodeableConcept What the purpose of this list is --></code>
 <subject><!-- 0..1 Reference(Patient|Group|Device|Location) 
     If all resources have the same subject --></subject>
 <source><!-- 0..1 Reference(Practitioner|Patient|Device) 
     Who and/or what defined the list contents --></source>
 <status value="[code]"/><!-- 1..1 current | retired | entered-in-error -->
 <date value="[dateTime]"/><!-- 0..1 When the list was prepared -->
 <orderedBy><!-- 0..1 CodeableConcept What order the list has --></orderedBy>
 <mode value="[code]"/><!-- 1..1 working | snapshot | changes -->
 <note value="[string]"/><!-- 0..1 Comments about the note -->
 <entry>  <!--  0..* Entries in the list -->
  <flag><!-- 0..* CodeableConcept Workflow information about this item --></flag>
  <deleted value="[boolean]"/><!--  0..1 If this item is actually marked as deleted -->
  <date value="[dateTime]"/><!-- 0..1 When item added to list -->
  <item><!-- 1..1 Reference(Any) Actual entry --></item>
 </entry>
 <emptyReason><!--  0..1 CodeableConcept Why list is empty --></emptyReason>
</List>

JSON Template

{
  "resourceType" : "List",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Business identifier
  "title" : "<string>", // Descriptive name for the list
  "code" : { CodeableConcept }, // What the purpose of this list is
  "subject" : { Reference(Patient|Group|Device|Location) }, // 
     If all resources have the same subject
  "source" : { Reference(Practitioner|Patient|Device) }, // 
     Who and/or what defined the list contents
  "status" : "<code>", // R!  current | retired | entered-in-error
  "date" : "<dateTime>", // When the list was prepared
  "orderedBy" : { CodeableConcept }, // What order the list has
  "mode" : "<code>", // R!  working | snapshot | changes
  "note" : "<string>", // Comments about the note
  "entry" : [{ // C? Entries in the list
    "flag" : [{ CodeableConcept }], // Workflow information about this item
    "deleted" : <boolean>, // C? If this item is actually marked as deleted
    "date" : "<dateTime>", // When item added to list
    "item" : { Reference(Any) } // R!  Actual entry
  }],
  "emptyReason" : { CodeableConcept } // C? Why list is empty
}

Structure

Name	Flags	Card.	Type	Description & Constraints
List	I		DomainResource	Information summarized from a list of other resources The deleted flag can only be used if the mode of the list is "changes" A list can only have an emptyReason if it is empty
identifier		0..*	Identifier	Business identifier
title	Σ	0..1	string	Descriptive name for the list
code	Σ	0..1	CodeableConcept	What the purpose of this list is ListPurpose (Example)
subject	Σ	0..1	Patient \| Group \| Device \| Location	If all resources have the same subject
source	Σ	0..1	Practitioner \| Patient \| Device	Who and/or what defined the list contents
status	?! Σ	1..1	code	current \| retired \| entered-in-error ListStatus (Required)
date	Σ	0..1	dateTime	When the list was prepared
orderedBy		0..1	CodeableConcept	What order the list has ListOrder (Preferred)
mode	?! Σ	1..1	code	working \| snapshot \| changes ListMode (Required)
note		0..1	string	Comments about the note
entry	I	0..*	Element	Entries in the list
flag		0..*	CodeableConcept	Workflow information about this item ListItemFlag (Example)
deleted	?! I	0..1	boolean	If this item is actually marked as deleted
date		0..1	dateTime	When item added to list
item		1..1	Any	Actual entry
emptyReason	I	0..1	CodeableConcept	Why list is empty ListEmptyReason (Preferred)

UML Diagram

XML Template

<List xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Business identifier --></identifier>
 <title value="[string]"/><!-- 0..1 Descriptive name for the list -->
 <code><!-- 0..1 CodeableConcept What the purpose of this list is --></code>
 <subject><!-- 0..1 Reference(Patient|Group|Device|Location) 
     If all resources have the same subject --></subject>
 <source><!-- 0..1 Reference(Practitioner|Patient|Device) 
     Who and/or what defined the list contents --></source>
 <status value="[code]"/><!-- 1..1 current | retired | entered-in-error -->
 <date value="[dateTime]"/><!-- 0..1 When the list was prepared -->
 <orderedBy><!-- 0..1 CodeableConcept What order the list has --></orderedBy>
 <mode value="[code]"/><!-- 1..1 working | snapshot | changes -->
 <note value="[string]"/><!-- 0..1 Comments about the note -->
 <entry>  <!--  0..* Entries in the list -->
  <flag><!-- 0..* CodeableConcept Workflow information about this item --></flag>
  <deleted value="[boolean]"/><!--  0..1 If this item is actually marked as deleted -->
  <date value="[dateTime]"/><!-- 0..1 When item added to list -->
  <item><!-- 1..1 Reference(Any) Actual entry --></item>
 </entry>
 <emptyReason><!--  0..1 CodeableConcept Why list is empty --></emptyReason>
</List>

JSON Template

{
  "resourceType" : "List",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Business identifier
  "title" : "<string>", // Descriptive name for the list
  "code" : { CodeableConcept }, // What the purpose of this list is
  "subject" : { Reference(Patient|Group|Device|Location) }, // 
     If all resources have the same subject
  "source" : { Reference(Practitioner|Patient|Device) }, // 
     Who and/or what defined the list contents
  "status" : "<code>", // R!  current | retired | entered-in-error
  "date" : "<dateTime>", // When the list was prepared
  "orderedBy" : { CodeableConcept }, // What order the list has
  "mode" : "<code>", // R!  working | snapshot | changes
  "note" : "<string>", // Comments about the note
  "entry" : [{ // C? Entries in the list
    "flag" : [{ CodeableConcept }], // Workflow information about this item
    "deleted" : <boolean>, // C? If this item is actually marked as deleted
    "date" : "<dateTime>", // When item added to list
    "item" : { Reference(Any) } // R!  Actual entry
  }],
  "emptyReason" : { CodeableConcept } // C? Why list is empty
}

Alternate definitions: Schema/Schematron, Resource Profile (XML, JSON)

6.1.3.1 Terminology Bindings

Path	Definition	Type	Reference
List.code	What the purpose of a list is	Example	http://hl7.org/fhir/vs/list-example-codes
List.status	The current state of the list	Required	http://hl7.org/fhir/list-status
List.orderedBy	What order applies to the items in a list	Preferred	http://hl7.org/fhir/vs/list-order
List.mode	The processing mode that applies to this list	Required	http://hl7.org/fhir/list-mode
List.entry.flag	Codes that provide further information about the reason and meaning of the item in the list	Example	http://hl7.org/fhir/vs/list-item-flag
List.emptyReason	If a list is empty, why it is empty	Preferred	http://hl7.org/fhir/vs/list-empty-reason

Path

Definition

Type

Reference

List.code

What the purpose of a list is

Example

http://hl7.org/fhir/vs/list-example-codes

List.status

The current state of the list

Required

http://hl7.org/fhir/list-status

List.orderedBy

What order applies to the items in a list

Preferred

http://hl7.org/fhir/vs/list-order

List.mode

The processing mode that applies to this list

Required

http://hl7.org/fhir/list-mode

List.entry.flag

Codes that provide further information about the reason and meaning of the item in the list

Example

http://hl7.org/fhir/vs/list-item-flag

List.emptyReason

If a list is empty, why it is empty

Preferred

http://hl7.org/fhir/vs/list-empty-reason

6.1.3.2 Constraints

lst-1: A list can only have an emptyReason if it is empty (xpath: not(exists(f:emptyReason) and exists(f:entry)))
lst-2: The deleted flag can only be used if the mode of the list is "changes" (xpath: (f:mode/@value = 'changes') or not(exists(f:entry/f:item/f:deleted)))

6.1.4 List Mode & Item Deleted

There are several different kinds of uses for a List resource:

working	This list is the master list, maintained in an ongoing fashion with regular updates as the real world list it is tracking changes.
snapshot	This list was prepared as a snapshot. It should not be assumed to be current.
changes	The list is prepared as a statement of changes that have been made or recommended.

The final mode - a changes list, may include deleted items. A typical case is a medication list in a discharge summary, where the list includes items that have been both added and deleted. In order to ensure that the list is safe to process, any item where the flag implies that the item has actually been deleted SHALL have the deleted element set to true.

Note that there is no implication about the status of a resource that has been deleted. The only statement that is made is that the resource has been dropped from the list. However applications should ensure that the implication of adding or deleting items from the list is consistent with the logical status of the resource and its contents.

A proper use of List.mode = "changes" with a deleted resource is in a medications list for a discharge summary. See Example "med-list". An improper use would be if the list was a working list of patient medications in a clinical tracking system, and list item flags were used to implement version tracking history within the resource.

6.1.5 Narrative Content

The narrative portion of the List resource should contain a summary of the items in the list, their key information, along with a human-readable summary of their flags (if present). The narrative may be generated from the data content and/or narrative of the resources referred to in the list, or it may be a narrative written by a human which is partially or completely matched by structured data in the linked resources, or human written narrative may be the only content if the list has no entries (which would equate to a narrative only section in a document).

An HTML table is the recommended approach, though this is not required. Each List.item should appear in the narrative for the resource. I.e. It SHALL not be necessary to retrieve the list items in order to have a human-readable rendering of the content. In addition, if the List.text.status is "generated", then the narrative should not suggest the list contains items for which there are no corresponding List.item elements. If the list has flags, the representation should make clear use of visual hints (borders, lines, bullet marks, etc.) to ensure that human readers do not get confused about which flags belong with which item on space-poor displays (e.g. to prevent wrapping from separating the flags from the items).

Note that when a List resource is used in a Document, the narrative of the list is part of the attested content of the document.

In a dynamic environment, the narrative content of the list will be limited to the version of the linked resources at the time the list was last updated. It may be even earlier if the narrative isn't updated to reflect the most recent version of all referenced resources at each update. Best practice for 'working' lists is to update the narrative to reflect the most recent content of all list elements each time the list is revised. Lists should therefore not be relied on as a real-time view of the referenced content. There are a few possible approaches to work around this issue:

Provide minimal information about the listed resources, possibly limited to only a link. (Not recommended as this severely limits the usefulness of the narrative and is particularly problematic for things like documents where the only attested content might be the List narrative)
Include only "generated" narrative, so the retriever can easily generate their own "current" view of the list by retrieving the referenced resources, ignoring the fixed narrative.
The server hosting the list can subscribe to all referenced resources and auto-update the narrative each time one of the referenced resources changes (or at least on a semi-frequent basis)

6.1.6 Empty Reason

If the list is empty, there could be several different reasons why this is so. For example:

There are no appropriate entries for the list (i.e. the patient has no known medications/allergies/history)
The sender (human or system) deemed that these were not related to this context of patient care (usually for privacy related reasons)
The source system doesn't support these type of entries
The information to populate the list wasn't gathered - i.e. "Not asked"

Given these possibilities, and the common and significant first case, source systems SHOULD provide an empty reason if the list is empty. Because of the importance of this case, the special value "nil-known" should be used when there are no (significant) entries in this context of care. Note that this concept is sometimes described differently, such as "patient denies taking medications", or "patient was unable to identify any relevant medical history".

When receiving a list, systems should not assume that the list is complete (some entries may have been withheld for a variety of reasons), unless there are specific trading partner arrangements in place or, if the list is empty, that there are actually nil known, unless the "nil-known" code is present.

If the list is empty, the narrative should contain text equivalent to the empty reason.

6.1.7 Search Parameters

Search parameters for this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

Name	Type	Description	Paths
code	token	What the purpose of this list is	List.code
date	date	When the list was prepared	List.date
empty-reason	token	Why list is empty	List.emptyReason
item	reference	Actual entry	List.entry.item (Any)
notes	string	Comments about the note	List.note
patient	reference	If all resources have the same subject	List.subject (Patient)
source	reference	Who and/or what defined the list contents	List.source (Device, Patient, Practitioner)
status	token	current \| retired \| entered-in-error	List.status
subject	reference	If all resources have the same subject	List.subject (Device, Location, Patient, Group)
title	string	Descriptive name for the list	List.title