2nd DSTU Draft For Comment

This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). 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

List resources are used in many places, including allergies, medications, alerts, medical history, etc.

6.1.2 Boundaries and Relationships

There are 2 resources that provide for constructing collections of other resources:

  • This List resource - enumerates a collection of resources that are in some list, and provides features for managing the list. The list resource references other resources
  • 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

6.1.3 Resource Content

Structure

NameFlagsCard.TypeDescription & Constraintsdoco
.. List IDomainResourceInformation 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..*IdentifierBusiness identifier
... code 0..1CodeableConceptWhat the purpose of this list is
ListPurpose (Example)
... subject 0..1Patient | Group | Device | LocationIf all resources have the same subject
... source 0..1Practitioner | Patient | DeviceWho and/or what defined the list contents
... date 0..1dateTimeWhen the list was prepared
... ordered M0..1booleanWhether items in the list have a meaningful order
... mode M1..1codeworking | snapshot | changes
ListMode (Required)
... entry I0..*ElementEntries in the list
.... flag 0..*CodeableConceptWorkflow information about this item
ListItemFlag (Example)
.... deleted M I0..1booleanIf this item is actually marked as deleted
.... date 0..1dateTimeWhen item added to list
.... item 1..1AnyActual entry
... emptyReason I0..1CodeableConceptWhy list is empty
ListEmptyReason (Incomplete)

UML Diagram

List (DomainResource)Identifier for the List assigned for business purposes outside the context of FHIRidentifier : Identifier 0..*This code defines the purpose of the list - why it was createdcode : CodeableConcept 0..1 « (What the purpose of a list isListPurpose) »The common subject (or patient) of the resources that are in the list, if there is onesubject : Reference(Patient|Group|Device|Location) 0..1The entity responsible for deciding what the contents of the list weresource : Reference(Practitioner|Patient|Device) 0..1The date that the list was prepareddate : dateTime 0..1Whether items in the list have a meaningful order (this element modifies the meaning of other elements)ordered : boolean 0..1How this list was prepared - whether it is a working list that is suitable for being maintained on an ongoing basis, or if it represents a snapshot of a list of items from another source, or whether it is a prepared list where items may be marked as added, modified or deleted (this element modifies the meaning of other elements)mode : code 1..1 « The processing mode that applies to this listListMode »If the list is empty, why the list is emptyemptyReason : CodeableConcept 0..1 « If a list is empty, why it is emptyListEmptyReason+ »EntryThe flag allows the system constructing the list to make one or more statements about the role and significance of the item in the listflag : CodeableConcept 0..* « (Codes that provide further information about the reason and meaning of the item in the listListItemFlag) »True if this item is marked as deleted in the list (this element modifies the meaning of other elements)deleted : boolean 0..1When this item was added to the listdate : dateTime 0..1A reference to the actual resource from which data was deriveditem : Reference(Any) 1..1Entries in this listentry0..*

XML Template

<List xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Business identifier --></identifier>
 <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>
 <date value="[dateTime]"/><!-- 0..1 When the list was prepared -->
 <ordered value="[boolean]"/><!-- 0..1 Whether items in the list have a meaningful order -->
 <mode value="[code]"/><!-- 1..1 working | snapshot | changes -->
 <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

{doco
  "resourceType" : "List",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Business identifier
  "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
  "date" : "<dateTime>", // When the list was prepared
  "ordered" : <boolean>, // Whether items in the list have a meaningful order
  "mode" : "<code>", // R! working | snapshot | changes
  "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

NameFlagsCard.TypeDescription & Constraintsdoco
.. List IDomainResourceInformation 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..*IdentifierBusiness identifier
... code 0..1CodeableConceptWhat the purpose of this list is
ListPurpose (Example)
... subject 0..1Patient | Group | Device | LocationIf all resources have the same subject
... source 0..1Practitioner | Patient | DeviceWho and/or what defined the list contents
... date 0..1dateTimeWhen the list was prepared
... ordered M0..1booleanWhether items in the list have a meaningful order
... mode M1..1codeworking | snapshot | changes
ListMode (Required)
... entry I0..*ElementEntries in the list
.... flag 0..*CodeableConceptWorkflow information about this item
ListItemFlag (Example)
.... deleted M I0..1booleanIf this item is actually marked as deleted
.... date 0..1dateTimeWhen item added to list
.... item 1..1AnyActual entry
... emptyReason I0..1CodeableConceptWhy list is empty
ListEmptyReason (Incomplete)

UML Diagram

List (DomainResource)Identifier for the List assigned for business purposes outside the context of FHIRidentifier : Identifier 0..*This code defines the purpose of the list - why it was createdcode : CodeableConcept 0..1 « (What the purpose of a list isListPurpose) »The common subject (or patient) of the resources that are in the list, if there is onesubject : Reference(Patient|Group|Device|Location) 0..1The entity responsible for deciding what the contents of the list weresource : Reference(Practitioner|Patient|Device) 0..1The date that the list was prepareddate : dateTime 0..1Whether items in the list have a meaningful order (this element modifies the meaning of other elements)ordered : boolean 0..1How this list was prepared - whether it is a working list that is suitable for being maintained on an ongoing basis, or if it represents a snapshot of a list of items from another source, or whether it is a prepared list where items may be marked as added, modified or deleted (this element modifies the meaning of other elements)mode : code 1..1 « The processing mode that applies to this listListMode »If the list is empty, why the list is emptyemptyReason : CodeableConcept 0..1 « If a list is empty, why it is emptyListEmptyReason+ »EntryThe flag allows the system constructing the list to make one or more statements about the role and significance of the item in the listflag : CodeableConcept 0..* « (Codes that provide further information about the reason and meaning of the item in the listListItemFlag) »True if this item is marked as deleted in the list (this element modifies the meaning of other elements)deleted : boolean 0..1When this item was added to the listdate : dateTime 0..1A reference to the actual resource from which data was deriveditem : Reference(Any) 1..1Entries in this listentry0..*

XML Template

<List xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <!-- from DomainResource: text, contained, extension, and modifierExtension -->
 <identifier><!-- 0..* Identifier Business identifier --></identifier>
 <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>
 <date value="[dateTime]"/><!-- 0..1 When the list was prepared -->
 <ordered value="[boolean]"/><!-- 0..1 Whether items in the list have a meaningful order -->
 <mode value="[code]"/><!-- 1..1 working | snapshot | changes -->
 <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

{doco
  "resourceType" : "List",
  // from Resource: id, meta, implicitRules, and language
  // from DomainResource: text, contained, extension, and modifierExtension
  "identifier" : [{ Identifier }], // Business identifier
  "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
  "date" : "<dateTime>", // When the list was prepared
  "ordered" : <boolean>, // Whether items in the list have a meaningful order
  "mode" : "<code>", // R! working | snapshot | changes
  "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), Questionnaire

6.1.3.1 Terminology Bindings

PathDefinitionTypeReference
List.code What the purpose of a list isExamplehttp://hl7.org/fhir/vs/list-example-codes
List.mode The processing mode that applies to this listFixedhttp://hl7.org/fhir/list-mode
List.entry.flag Codes that provide further information about the reason and meaning of the item in the listExamplehttp://hl7.org/fhir/vs/list-item-flag
List.emptyReason If a list is empty, why it is emptyIncompletehttp://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:

workingThis list is the master list, maintained in an ongoing fashion with regular updates as the real world list it is tracking changes.
snapshotThis list was prepared as a snapshot. It should not be assumed to be current.
changesThe 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 key properties of the items in the list, along with a human-readable summary of their flags (if present).

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 should not be necessary to retrieve the list items in order to have a human-readable rendering of the content. In addiiton, 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).

This means that the narrative content of the list will be limited to the version of the contained 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.

NameTypeDescriptionPaths
codetokenWhat the purpose of this list isList.code
datedateWhen the list was preparedList.date
empty-reasontokenWhy list is emptyList.emptyReason
itemreferenceActual entryList.entry.item
(Any)
patientreferenceIf all resources have the same subjectList.subject
(Patient)
sourcereferenceWho and/or what defined the list contentsList.source
(Device, Patient, Practitioner)
subjectreferenceIf all resources have the same subjectList.subject
(Device, Location, Patient, Group)