Visor de Bundles FHIR: Cómo Inspeccionar un Bundle Recibido

El Bundle Ha Llegado. ¿Y Ahora Qué?

Un proveedor, un hospital socio o un compañero te envía un Bundle FHIR y te pide que "le eches un vistazo". El fichero son unos cientos de kilobytes de JSON anidado. Recorrerlo en un editor no te dice casi nada útil en los primeros diez minutos, y las preguntas que de verdad necesitas responder —¿es el paciente correcto?, ¿falta algo?, ¿esto cargará en nuestro sistema?— no se contestan leyendo llaves.

Esto es un checklist para esa situación: qué mirar primero, en qué orden y qué hallazgos deberían impedirte aceptar el bundle. Da por hecho que sabes leer JSON pero no que te hayas memorizado la especificación. Todo se puede hacer con el Explorador de Bundles FHIR, que analiza en tu navegador para que un bundle lleno de datos clínicos nunca salga de tu máquina. Si la estructura del Bundle en sí no te resulta familiar —type, entry, fullUrl y demás—, lee antes Qué Es un Bundle FHIR, porque las comprobaciones de abajo asumen que sabes para qué sirve cada parte.

Paso Uno: Confirma Qué Has Recibido en Realidad

Antes de nada, establece la forma del fichero. La gente dice "bundle" con soltura, y lo que llega es a menudo otra cosa: un recurso suelto, un NDJSON de un trabajo de exportación masiva, o un array JSON de recursos producido por alguien ejecutando jq -s sobre una exportación. Las tres son entregas legítimas; ninguna es un Bundle. Un visor que detecta la forma automáticamente te ahorra adivinar: el Explorador reconoce un Bundle por su resourceType, un recurso suelto por tener un resourceType que no es Bundle, NDJSON por no ser analizable como un solo documento mientras cada línea abre un objeto nuevo, y un array suelto por sus corchetes.

Conocer la forma importa porque cambia lo que puedes esperar. Solo un Bundle tiene fullUrl a nivel de entrada, y solo un Bundle tiene metadatos de bundle como type y timestamp. Juzgar una exportación NDJSON con las expectativas de un Bundle produce una lista de quejas sobre cosas que nunca debieron estar ahí.

Paso Dos: Lee el Recuento de Recursos

La vista más informativa de un bundle nuevo es el recuento de recursos por resourceType. Se lee en cinco segundos y responde de golpe a la mayoría de las preguntas de cordura.

Busca tres cosas. ¿Falta algo por completo? Un resumen clínico con 40 Observations y cero Patients no tiene sujeto: las observaciones referencian a un paciente que no está en el fichero. ¿Son plausibles las proporciones? Un Patient y 3.000 Observations es normal en un flujo de monitorización y sospechoso en un informe de alta. ¿Hay tipos que no esperabas? Un Provenance o un AuditEvent inesperado es inofensivo; un OperationOutcome inesperado suele significar que la exportación del emisor falló parcialmente y el error acabó empaquetado junto a los datos.

Comprueba también si el recuento está completo. Un visor que lee en local tiene que tener límites —el Explorador analiza hasta 25 MB y 20.000 recursos— y lo que importa es que te avise cuando alcanza uno. Informa del número de recursos descartados de forma explícita, de modo que una lectura truncada nunca se confunde con un bundle pequeño. Si ves un recuento de descartes, pide que dividan el fichero en origen antes de sacar cualquier conclusión del recuento.

Paso Tres: Revisa una Tabla por Tipo de Recurso

Leer JSON anidado es una mala forma de detectar patrones. Leer una tabla es una buena. Aplanar cada tipo de recurso en filas y columnas —id, estado, código, valor, fecha, referencia al sujeto— hace visibles de un vistazo clases enteras de problema que de otro modo hay que buscar recurso a recurso.

Lo que salta a la vista en una tabla y se esconde en el JSON: una columna entera vacía, señal de que un campo que esperabas no está en ningún registro; una columna de estado con entered-in-error en filas que nadie mencionó; fechas agrupadas en un único día inverosímil, la firma de una carga retroactiva o de un conjunto de pruebas; una columna de valores con unidades inconsistentes, unas filas en mg/dL y otras en mmol/L; o una columna de referencia al sujeto donde un puñado de filas apunta a un sitio distinto del resto.

Esto último merece una mirada específica, porque un bundle descrito como relativo a un paciente debería tener un único valor distinto en sus columnas de referencia al sujeto. Ordenar esa columna y ver dos valores es una de las comprobaciones de cinco segundos más rentables que puedes hacer sobre un bundle clínico. Si quieres llevar la tabla más lejos —a una hoja de cálculo para conciliar—, las decisiones sobre valores repetidos y la importación segura en Excel están en Cómo Convertir un Bundle FHIR a CSV Sin Perder Datos.

Paso Cuatro: Sigue las Referencias

Un Bundle es un grafo, no una lista. Su significado vive en las aristas: una Observation apunta a su sujeto, un Encounter a su paciente y a su proveedor, una Condition tanto al paciente como al encuentro en el que se registró. Inspeccionar los nodos sin inspeccionar las aristas te dice que los datos existen, pero no si encajan entre sí.

En la práctica, navegar las referencias significa poder pulsar una referencia y aterrizar en el recurso que nombra y —igual de útil— poder preguntar qué recursos apuntan hacia el que estás mirando. Las referencias entrantes son la forma de responder "qué sabemos realmente de este paciente en este fichero": seleccionas el Patient y las Observations, Conditions, Encounters y MedicationRequests que lo referencian son la respuesta. También es la forma de detectar huérfanos: recursos a los que nada apunta y que no apuntan a nada, que suelen haber llegado por error.

La resolución dentro de un bundle usa más de una clave, y conviene saberlo para que los resultados no sorprendan. Un recurso es direccionable por resourceType/id —la forma de referencia relativa— y, cuando la entrada lo lleva, por su fullUrl. Esa segunda clave es lo que hace funcionar las referencias urn:uuid:: un bundle de transacción montado antes de que el servidor asignase ids reales usa UUID como identidad temporal, con el fullUrl de cada entrada guardando el UUID y las referencias apuntando a él. Como un fullUrl del estilo http://ejemplo.org/fhir/Patient/123 también termina en una forma relativa utilizable, su cola Patient/123 se trata igualmente como dirección, que es como se refieren normalmente entre sí las entradas de un mismo bundle. Cuando dos recursos reclaman la misma clave, gana el primero, de modo que un id duplicado no puede secuestrar a un recurso anterior.

Paso Cinco: Mira con Lupa las Referencias No Resueltas

Una referencia no resuelta es aquella cuyo destino no está presente en lo que has cargado. Es el defecto más común en un bundle recibido y el que más probablemente rompa el sistema receptor, así que merece una pasada propia.

Es esencial que un visor las saque a la luz en lugar de ignorarlas discretamente, e igual de esencial que no intente arreglarlas descargando nada. El Explorador resuelve referencias únicamente en local y nunca hace una petición de red para perseguir una. Es una decisión de privacidad, no una carencia: una cadena de referencia contiene un identificador, y preguntar por él a un servidor externo revela que se está consultando un registro concreto, exactamente la fuga que una herramienta de procesamiento local existe para evitar.

Ahora bien, no toda referencia no resuelta es un error, y confundir una legítima con un defecto cuesta mucho tiempo. Recorre estas causas en orden:

• El destino realmente no se envió. Una Observation que referencia a Patient/123 en un bundle sin ningún Patient. Es un defecto real si el bundle debía ser autocontenido: vuelve al emisor.
• La referencia es absoluta y externa por diseño. Un puntero a un Practitioner o una Organization en el servidor del emisor, deliberadamente no incluido por ser dato de referencia compartido y no dato de paciente. Comportamiento correcto, nada que arreglar.
• Estás mirando un fichero de una exportación multifichero. En una exportación masiva dividida por tipo, la referencia al sujeto de una Observation no puede resolverse si solo abres el fichero de Observations. Esperado, no un defecto.
• Una referencia urn:uuid: sin fullUrl coincidente. El bundle usa identidad temporal pero la entrada que debería llevar el UUID correspondiente falta o se montó mal. Este sí es un error de construcción y fallará al enviarse.
• Un casi-acierto en la cadena de referencia. Mayúsculas mal en el tipo de recurso, una barra final de más, un sufijo de versión como Patient/123/_history/2 donde se esperaba la forma simple. Fácil de corregir en cuanto se ve, invisible hasta que lo miras.

Si manejas bundles con regularidad conviene interiorizar las diferencias entre estas formas —relativa, absoluta, UUID, contenida—; Cómo Funcionan las Referencias en FHIR repasa cada una y cuándo es apropiada.

Lo Que un Visor Deliberadamente No Hace

Ser claro con el alcance evita una falsa sensación de garantía. Un visor de bundles es de solo lectura: analiza, tabula, indexa referencias y exporta, y nunca modifica la entrada. Tampoco valida. Un recurso al que le falte un elemento obligatorio, que lleve un código del sistema equivocado o que incumpla las reglas de slicing de un perfil se mostrará tan tranquilo: el trabajo del visor es enseñarte lo que hay, no juzgarlo contra una StructureDefinition. La comprobación de conformidad es una disciplina aparte con su propio vocabulario de fallos, cubierta en Errores de Cardinalidad y Slicing en FHIR.

Una nota más de alcance: el explorador trabaja solo con JSON, no con la serialización XML. En la práctica rara vez es una limitación, porque JSON domina el intercambio FHIR y toda exportación masiva es JSON por especificación, pero si un socio te envía XML tendrás que convertirlo antes de inspeccionarlo.

Por Qué "Visor Online" Debería Significar "En Tu Navegador"

La mayoría de los resultados de búsqueda para un visor de bundles son servicios alojados que suben tu fichero a un servidor para procesarlo. Para un bundle sintético de pruebas eso está bien. Para uno real es una comunicación de información sanitaria protegida a un tercero, hecha a la ligera, normalmente sin contrato de encargado de tratamiento y a menudo repetida una docena de veces a lo largo de una tarde de depuración. La distinción que importa no es si una herramienta es online: es si el procesamiento ocurre en su máquina o en la tuya. Una herramienta que analiza en JavaScript dentro de tu pestaña es online en el sentido de que llegas a ella por la web y local en el sentido de que tus datos se quedan donde están, y lo segundo lo puedes comprobar tú mismo en el panel de red del navegador.

Conclusión

Inspeccionar un bundle recibido es una rutina de cinco pasos: confirmar la forma, leer el recuento de recursos, revisar una tabla por tipo, seguir las referencias en ambos sentidos y clasificar después cada referencia no resuelta como defecto real o puntero externo esperado. La mayoría de los problemas que rompen una carga posterior —un sujeto ausente, un paciente duplicado, un fichero truncado, un urn:uuid: roto— afloran en esos cinco pasos en menos de diez minutos. Ejecútalos en el Explorador de Bundles FHIR, recuerda que lee pero no valida, y podrás hacer toda la revisión sin que los datos del paciente salgan de tu máquina.