• Content
• Examples
• Detailed Descriptions
• Mappings
• Profiles & Extensions
• Operations
• R4 Conversions
• Search Params

2.7 Resource List - Content

FHIR Infrastructure Work Group

Maturity Level: 1

Trial Use

Security Category: Not Classified

Compartments: Device, Patient, Practitioner

A List is a curated collection of resources, for things such as problem lists, allergy lists, facility list, organization list, etc.

2.7.3 References to this Resource

• Resource References: MeasureReport
• Extension References: category and changeBase

2.7.4 Resource Content

 

Additional definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions, the spreadsheet version & the dependency analysis

2.7.4.1 Terminology Bindings

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	Example use codes for the List resource - typical kinds of use.	Example	ExampleUseCodesForList
List.orderedBy	Base values for the order of the items in a list resource.	Preferred	ListOrderCodes
List.entry.flag	Example Item Flags for the List Resource. In this case, these are the kind of flags that would be used on a medication list at the end of a consultation.	Example	PatientMedicineChangeTypes
List.emptyReason	General reasons for a list to be empty. Reasons are either related to a summary list (i.e. problem or medication list) or to a workflow related list (i.e. consultation list).	Preferred	ListEmptyReasons

2.7.4.2 Constraints

2.7.5 Querying Lists vs. the underlying resources

When a client system is interested in a patient's medications, allergies, problems, family history or other information typically handled via List, they have three options:

• They can query for List instances of the appropriate type; or
• They can query against the resource endpoint for the resources that make up the list (e.g. AllergyIntolerance, Condition MedicationUsage, etc.), possibly filtering by time, etc.
• They can query against the resource endpoint, requesting one of the Current resource lists

Querying directly against the clinical resource endpoints will provide an un-curated view of information. A server may contain records that were part of various clinical documents, referrals and other submission sources that might not necessarily be considered wholly accurate or current, but which must be retained "as is" to provide a record of what data was received or seen by a clinician at a particular point in time.

On the other hand, lists are almost always curated. They will include only those records deemed by the author of the list to be both current and accurate. This can be both an advantage and a disadvantage. Lists are less likely to include irrelevant content, but there's a risk that they won't be completely up-to-date (new content may have been added that's more recent than when a given list was last updated). It's also possible that the list author's notion of "current" or "relevant" may differ from the perspective of the user performing the query. Also, there's the challenge that multiple lists may exist, with different author and different perspectives

The Current resource lists get around the problem of multiple lists and make it clear which list is considered authoritative, but not all systems will necessarily support this capability, and there's still the possibility that the list won't be completely up-to-date or will exclude information that is of interest to the querying system.

There's no right and wrong way to retrieve allergy, medication and other such information. Sometimes retrieving the "current" medication list will provide the best results, sometimes querying the raw records will provide better results. Sometimes providing the contents of the list plus a filtered view of the raw records may give the most useful information. Determining the most appropriate approach will depend on the needs of the user as well as the types of data sources for information held on the server and patterns of list maintenance. Client systems may well need to adapt their behavior in different environments if they can't count on consistent server behavior.

2.7.6 List Order

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 the order in which the patients are to be visited, or it may be an unsorted list of patients to be visited in any order.

The List resource has an orderedBy element that, if present, specifies the meaning of the item order. Note, however, 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.

2.7.7 List Mode & Item Deleted

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

2.7.7.1 The processing mode that applies to this list.

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 point-in-time list that shows what changes have been made or recommended. E.g. a discharge medication list showing what was added and removed during an encounter.

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 might 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 section of 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.

2.7.8 Efficiency and size issues

Some kinds of List resources may grow to a considerable size, and handling them may require more care than typical resources. Some approaches to consider include:

• Reading portions of the list resource using GraphQL
• Using the _list parameter rather than retrieving the list
• Changing the resource using the PATCH interaction rather than PUTting the whole resource

2.7.9 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. 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 a 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).

2.7.10 Empty Reason

If a 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 types of entries
• The information to populate the list wasn't gathered - i.e. "Not asked"

Given these possibilities - especially the common and significant first case - for many kinds of lists, source systems SHOULD provide an empty reason if the list is empty. Because of the importance of the first 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 a list is empty, the narrative should contain text equivalent to the empty reason.

Note that there are also many kinds of lists that can be empty with no need for an empty reason (example)

2.7.11 Using the Deleted Flag

The deleted flag must be used when using a list with mode = change when a resource is to be removed from the list. For working and snapshot lists, deleted items can either be flagged as deleted or outright removed from the list. An item MAY transition from the former to the latter after a particular period of time has passed). The choice of flagging vs. outright removal is determined by the list author.

Applications processsing list SHOULD always check the deleted flag.

2.7.11.1 Managing large Lists

For operations to assist in adding to, removing from, or filtering contents of large Lists, see Operations for Large Resources.

2.7.11.2 Membership

Membership testing is used to test for active members of a List. Active entities in a list are entities:

• listed in List.entry.item and
• that do not have List.entry.deleted with a value of true.

Servers MAY impose additional membership constraints (e.g. based on modifier extensions).

2.7.12 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	Expression	In Common
code	token	What the purpose of this list is	List.code
date N	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 N	string	The annotation - text content (as markdown)	List.note.text
patient	reference	If all resources have the same subject	List.subject.where(resolve() is Patient) (Patient)
source	reference	Who and/or what defined the list contents (aka Author)	List.source (Practitioner, Organization, CareTeam, Device, Patient, PractitionerRole, RelatedPerson)
status N	token	current | retired | entered-in-error	List.status
subject	reference	If all resources have the same subject	List.subject (Practitioner, Group, Organization, Device, Patient, Location)
title N	string	Descriptive name for the list	List.title