Aspectos destacados de la búsqueda FHIR 2025.1 - Soporte de búsqueda relacionado con listas (_List, $find, Listas funcionales/"Actuales")

A veces es más conveniente, más eficiente y más seguro limitar las búsquedas FHIR a "listas" de recursos predefinidas.

Desde la versión v2025.1, soportamos varias funcionalidades relacionadas con listas en nuestro servidor FHIR.

Aquí las destacaré y os proporcionaré algunos ejemplos.

En general, podéis consultar los detalles sobre el recurso List en la documentación oficial de FHIR. 

Pero aquí tenéis una breve descripción basada en lo anterior:

El recurso List de FHIR representa una colección plana (opcionalmente ordenada) de registros utilizada para listas clínicas (por ejemplo, alergias, medicación, alertas, historiales) y para la gestión de flujos de trabajo (por ejemplo, seguimiento de pacientes, casos de enseñanza).
Las listas pueden ser homogéneas (un único tipo de recurso) o heterogéneas (tipos mezclados, por ejemplo, una lista de problemas que abarque Conditions, AllergyIntolerances y Procedures).
Usad List cuando necesitéis un conjunto seleccionado/filtrado que no pueda obtenerse mediante una consulta simple (por ejemplo, “alergias actuales” frente a todas las alergias registradas).
Consultar una List devuelve una instantánea curada por humanos en un momento determinado, mientras que consultar el endpoint del recurso normalmente devuelve un conjunto de datos más amplio, no curado, “tal como está ahora”.

En nuestras versiones más recientes (2025.1+) podéis encontrar un nuevo soporte para trabajar con Lists:

• El parámetro de búsqueda _list

Consultad la documentación FHIR relacionada para una descripción completa. Consultad también nuestra documentación relacionada para conocer los detalles del soporte disponible (específicamente sobre búsquedas a nivel de tipo frente a búsquedas a nivel de sistema).

Con esta funcionalidad podéis definir, por ejemplo, una List de ciertos recursos, como Encounters o Patients, que queráis buscar según ellos, sin tener que detallar todos como múltiples parámetros de búsqueda.

Por ejemplo, podría definir una List de Patients:

curl --location --request PUT 'http://myserver/fhir/r4/List/OrgAPatients' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: *******' \
--data '{
  "resourceType": "List",
  "id":"OrgAPatients",
  "status":"current",
  "mode":"snapshot",
  "entry": [
      {
        "item": {
           "reference": "Patient/2"
        }
      },
      {
        "item": {
           "reference": "Patient/3"
        }
      },
      {
        "item": {
           "reference": "Patient/4"
        }
      }
    ]
}'

Y luego buscarlos de esta manera:

curl --location 'http://myserver/fhir/r4/Patient?_list=OrgAPatients' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: *****'

Y recibir de vuelta una lista curada de los Patients que quería, en lugar de tener que “mencionar” a todos ellos en múltiples parámetros de búsqueda.

Y, por supuesto, hay muchos otros casos de uso.

• Listas funcionales (incluida la operación personalizada $update-functional)

Un tipo especial de listas son las Listas Funcionales (o listas de “Current Resource”).

Consultad la documentación FHIR relacionada para una descripción completa.

Para vuestra comodidad, aquí tenéis una breve descripción basada en lo anterior:

Muchos sistemas clínicos mantienen listas de pacientes “actuales” (por ejemplo, una lista de problemas actuales y una lista de medicación actual), pero FHIR no puede inferir de manera fiable la “actualidad” simplemente examinando una única instancia de recurso.

Usando Condition como ejemplo, el mismo tipo de recurso puede registrarse con múltiples fines legítimos (entrada curada en la lista de problemas, queja/diagnóstico de un encuentro, contexto de flujo de trabajo diagnóstico o datos de derivación entrante), y Condition no tiene un elemento que distinga claramente estos usos.

Dado que diferenciar entre actual y pasado requeriría alteraciones retrospectivas (generando problemas de integridad y firma digital), una búsqueda normal de Condition para un paciente devolverá más que solo los “problemas actuales” curados, y limitarla a “solo actuales” ocultaría otros registros importantes de Condition.

Por lo tanto, si un Condition (o un registro similar) forma parte de la “lista actual” de un paciente podría determinarse según si está referenciado desde la List correspondiente.

A través de la API REST, esto se expresa mediante el mecanismo de búsqueda _listutilizando nombres estándar de listas funcionales (por ejemplo, GET [base]/AllergyIntolerance?patient=42&_list=$current-allergies), y el servidor puede soportarlo sin necesariamente exponer una instancia de List independiente.

Existen varios nombres “comunes” de listas funcionales, como $current-problems, $current-medications, $current-allergies y $current-drug-allergies (un subconjunto de alergias). 

Para permitir el mantenimiento de estas Listas Funcionales, hemos definido una Operación Personalizada llamada $update-functional, que permite crear y actualizar este tipo de listas. Podéis consultar más detalles en nuestra documentación.

Por ejemplo, podéis definir una lista de alergias actuales de la siguiente manera:

curl --location 'http://fhirserver/fhir/r4/List/$update-functional?for=34&name=%5C%24current-allergies' \
--header 'Content-Type: application/fhir+json' \
--header 'Authorization: *****' \
--data '{
  "resourceType": "List",
  "status":"current",
  "mode":"working",
  "subject":  { "reference":"Patient/34" },
  "entry": [
      {
        "item": {
           "reference": "AllergyIntolerance/159"
        }
      },
      {
        "item": {
           "reference": "AllergyIntolerance/160"
        }
      },
      {
        "item": {
           "reference": "AllergyIntolerance/161"
        }
      }
    ]
}'

Esto creará/actualizará la lista $current-allergies para un paciente específico (ID 34 en el ejemplo anterior).

Tened en cuenta que incluyo el for= en la URL apuntando al ID del paciente, y en la List tengo 'subject ' haciendo referencia al paciente.

(También observad que, para el signo de dólar ($), he usado una barra invertida () antes, es decir: \$)

Y ahora, puedo solicitar el recurso AllergyIntolerance de este paciente, y en lugar de obtener todos, puedo pedir solo los “actuales”, tal como se definen en la List anterior.

Esto se vería así:

curl --location 'http://fhirserver/fhir/r4/AllergyIntolerance?patient=34&_list=%5C%24current-allergies' \
--header 'Authorization: *****'

Y esto devolvería un subconjunto de las alergias de este paciente, según la lista de alergias actuales.

Tened en cuenta que estamos usando el mismo parámetro de búsqueda _list mencionado anteriormente, solo que esta vez, en lugar de una “Custom List”, se utiliza una “Functional List”.

Tened en cuenta que podéis controlar los nombres de las listas funcionales (y, para cada lista, su parámetro de búsquedasubjecty el tipo de recurso subject; por ejemplo, en el ejemplo anterior el parámetro de búsqueda subject era patient y el tipo de recurso subject era Patient), a través de la configuración del endpoint FHIR, específicamente en los "Interactions Strategy Settings". Consultad la documentación relacionada aquí. Esto se ve así:

• Operación $find

Además, si simplemente queréis obtener la Lista Funcional en sí (para un subject en particular y de un tipo concreto), podéis usar la operación $find.

Consultad la documentación FHIR relacionada para una descripción completa. También consultad nuestra documentación relacionada.

Aquí tenéis un ejemplo, basado en el anterior:

curl --location 'http://fhirserver/fhir/r4/List/$find?patient=34&name=%5C%24current-allergies' \
--header 'Authorization: *****'

Esto devolverá la lista $current-allergies relacionada con este paciente, tal como se definió anteriormente mediante la función $update-functional.

Consultad la aplicación relacionada en Open Exchange, que incluye una colección de Postman con los ejemplos anteriores (y algunos más) e instrucciones para ejecutarlos contra el contenedor Docker de la plantilla del servidor FHIR de @Evgeny Shvarov (de hecho, el ejemplo anterior se creó a partir de este ejemplo, con un pequeño cambio… consultad los detalles en las instrucciones de uso de mi aplicación).