Resources supported by the List resource can be homogeneous – consisting of only one type of resource (e.g. allergy lists) 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; e.g. 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 Allergy Intolerances that are deemed to be “current”. Lists are allowed to contain other Lists, to create a nested collection of Lists.
Querying a List of resources such as Allergy Intolerance, Condition or Medication-related resources is different than querying the resource-specific endpoint. For example, a List of Allergy Intolerance resources would represent a curated point-in-time snapshot of the patient’s allergies and intolerances. On the other hand, querying the Allergy Intolerance endpoint would typically produce a larger set of records as it would both be non-curated (potentially containing duplicate or out-of-date records) and 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 might not have an appropriate curated 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” cannot have items that are Condition resources that do not have a verification Status of refuted.
The 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 may be curated and have specific business meaning.