STU 3 Candidate
This page is part of the FHIR Specification (v1.4.0: STU 3 Ballot 3). 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
| FHIR Infrastructure Work Group | Maturity Level: 1 | Compartments: Device, Patient, Practitioner |
A set of information summarized from a list of other resources.
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". Lists are allowed to contain other lists, so that there is a nested collection of lists.
Querying a List of resources such as AllergyIntolerance, Condition or Medication-related resources is different than querying the resource-specific end point. For example, a List of AllergyIntolerance would represent a curated point-in-time snapshot of the patient's allergies and intolerances. On the other hand, querying the AllergyIntolerance endpoint would typically produce a larger set of records as it would both be non-currated (potentially containing duplicate or out-of-date records) as well as current - generated based on information as of "now" rather than the last time a human manually revised the List resource instance. Which mechanism is most appropriate for data retrieval will vary by use-case. In some cases, systems may not have an appropriate currated List to query.
Note that the presence of an item in a List resource SHALL NOT change the meaning of any information that would be understood by looking at the item outside the context of the List, because items may be accessed directly outside the list by RESTful means, or after a document is processed. For example, a List with a code that means "refuted conditions" can not have items that are Condition resources that do not have a Condition.clinicalStatus of refuted.
There are five mechanisms in FHIR for communicating collections of resources:
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 measurereport
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 | |
 status | ?! Σ | 1..1 | code | current | retired | entered-in-error ListStatus (Required) |
| mode | ?! Σ | 1..1 | code | working | snapshot | changes ListMode (Required) |
| title | Σ | 0..1 | string | Descriptive name for the list |
| code | Σ | 0..1 | CodeableConcept | What the purpose of this list is Example Use Codes for List (Example) |
 subject | Σ | 0..1 | Reference(Patient | Group | Device | Location) | If all resources have the same subject |
| encounter | 0..1 | Reference(Encounter) | Context in which list created | |
| date | Σ | 0..1 | dateTime | When the list was prepared |
| source | Σ | 0..1 | Reference(Practitioner | Patient | Device) | Who and/or what defined the list contents (aka Author) |
| orderedBy | 0..1 | CodeableConcept | What order the list has List Order Codes (Preferred) | |
| note | 0..* | Annotation | Comments about the list | |
 entry | I | 0..* | BackboneElement | Entries in the list |
 flag | 0..1 | CodeableConcept | Status/Workflow information about this item Patient Medicine Change Types (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 | Reference(Any) | Actual entry | |
| emptyReason | I | 0..1 | CodeableConcept | Why list is empty List Empty Reasons (Preferred) |
| Documentation for this format | ||||
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> <status value="[code]"/><!-- 1..1 current | retired | entered-in-error --> <mode value="[code]"/><!-- 1..1 working | snapshot | changes --> <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> <encounter><!-- 0..1 Reference(Encounter) Context in which list created --></encounter> <date value="[dateTime]"/><!-- 0..1 When the list was prepared --> <source><!-- 0..1 Reference(Practitioner|Patient|Device) Who and/or what defined the list contents (aka Author) --></source> <orderedBy><!-- 0..1 CodeableConcept What order the list has --></orderedBy> <note><!-- 0..* Annotation Comments about the list --></note> <entry> <!--
0..* Entries in the list --> <flag><!-- 0..1 CodeableConcept Status/Workflow information about this item --></flag> <deleted value="[boolean]"/><!--
JSON Template
{
"resourceType" : "List",
// from Resource: id, meta, implicitRules, and language
// from DomainResource: text, contained, extension, and modifierExtension
"identifier" : [{ Identifier }], // Business identifier
"status" : "<code>", // R! current | retired | entered-in-error
"mode" : "<code>", // R! working | snapshot | changes
"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
"encounter" : { Reference(Encounter) }, // Context in which list created
"date" : "<dateTime>", // When the list was prepared
"source" : { Reference(Practitioner|Patient|Device) }, // Who and/or what defined the list contents (aka Author)
"orderedBy" : { CodeableConcept }, // What order the list has
"note" : [{ Annotation }], // Comments about the list
"entry" : [{ // C? Entries in the list
"flag" : { CodeableConcept }, // Status/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 | |
| status | ?! Σ | 1..1 | code | current | retired | entered-in-error ListStatus (Required) |
| mode | ?! Σ | 1..1 | code | working | snapshot | changes ListMode (Required) |
| title | Σ | 0..1 | string | Descriptive name for the list |
| code | Σ | 0..1 | CodeableConcept | What the purpose of this list is Example Use Codes for List (Example) |
| subject | Σ | 0..1 | Reference(Patient | Group | Device | Location) | If all resources have the same subject |
| encounter | 0..1 | Reference(Encounter) | Context in which list created | |
| date | Σ | 0..1 | dateTime | When the list was prepared |
| source | Σ | 0..1 | Reference(Practitioner | Patient | Device) | Who and/or what defined the list contents (aka Author) |
| orderedBy | 0..1 | CodeableConcept | What order the list has List Order Codes (Preferred) | |
| note | 0..* | Annotation | Comments about the list | |
| entry | I | 0..* | BackboneElement | Entries in the list |
| flag | 0..1 | CodeableConcept | Status/Workflow information about this item Patient Medicine Change Types (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 | Reference(Any) | Actual entry | |
| emptyReason | I | 0..1 | CodeableConcept | Why list is empty List Empty Reasons (Preferred) |
| Documentation for this format | ||||
XML Template
<List xmlns="http://hl7.org/fhir">
JSON Template
{
"resourceType" : "List",
// from Resource: id, meta, implicitRules, and language
// from DomainResource: text, contained, extension, and modifierExtension
"identifier" : [{ Identifier }], // Business identifier
"status" : "<code>", // R! current | retired | entered-in-error
"mode" : "<code>", // R! working | snapshot | changes
"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
"encounter" : { Reference(Encounter) }, // Context in which list created
"date" : "<dateTime>", // When the list was prepared
"source" : { Reference(Practitioner|Patient|Device) }, // Who and/or what defined the list contents (aka Author)
"orderedBy" : { CodeableConcept }, // What order the list has
"note" : [{ Annotation }], // Comments about the list
"entry" : [{ // C? Entries in the list
"flag" : { CodeableConcept }, // Status/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), Questionnaire
| Path | Definition | Type | Reference |
|---|---|---|---|
| List.status | The current state of the list | Required | ListStatus |
| List.mode | The processing mode that applies to this list | Required | ListMode |
| List.code | What the purpose of a list is | Example | Example Use Codes for List |
| List.orderedBy | What order applies to the items in a list | Preferred | List Order Codes |
| List.entry.flag | Codes that provide further information about the reason and meaning of the item in the list | Example | Patient Medicine Change Types |
| List.emptyReason | If a list is empty, why it is empty | Preferred | List Empty Reasons |
All lists are considered ordered - the order in which items literally appear in the list may be an important part of the meaning of the list. Reordering the items in a list may change the meaning of the list.
While a list always contains an ordered set of items, the significance of the order may be unknown, or it may be insignificant. As an example, consider a list of patients for a practitioner to visit. The list may be in order, where the patients are to be visited in the stated order, or just an unsorted list of patients to be visited in any order.
The list resource has a property orderedBy that, if
present, specifies the meaning of the item order. Note, though,
that the meaning of the order may be known implicitly rather
than specified in the orderedBy element.
Applications SHOULD NOT reorder the elements in a list unless they understand the impact of this on the meaning of the list.
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 | A list that indicates where changes have been made or recommended |
The most common mode is "snapshot" - a list that is accurate within the context it is used in but not current or maintained after that; e.g., medications on discharge in a discharge summary. Note that these lists usually have a status of 'current' - they were current when they were prepared. Some kinds of lists may be explicitly retired (particularly if mode = working), but most will not be maintained after creation.
A change list may include deleted items. Some examples of change lists are a reconciled list of allergies, a discharge medication list and a list with new, updated and deleted items in it - though these may not be lists that include changes (this is an implementation decision). 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.
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. The 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:
If the list is empty, there could be several different reasons why this is so. For example:
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.
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 |
| encounter | reference | Context in which list created | List.encounter (Encounter) |
| identifier | token | Business identifier | List.identifier |
| item | reference | Actual entry | List.entry.item (Any) |
| notes | string | Comments about the list | List.note |
| patient | reference | If all resources have the same subject | List.subject (Patient) |
| source | reference | Who and/or what defined the list contents (aka Author) | 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 |
© HL7.org 2011+. FHIR STU3 Candidate (v1.4.0-8139) generated on Thu, Mar 31, 2016 08:09+1100. QA Page
Links: Search |
Version History |
Table of Contents |
Compare to DSTU2 |
|
Propose a change