Perfiles FHIR: Diseño e Implementación con FSH, SUSHI y la CLI del Validador

Un perfil FHIR es un recurso StructureDefinition que restringe o extiende un recurso FHIR base para satisfacer los requisitos de un caso de uso, jurisdicción o guía de implementación específicos. Los perfiles declaran qué elementos son obligatorios, cuáles están prohibidos, qué cardinalidades aplican, qué sistemas de códigos deben vincularse a los elementos codificados y qué extensiones se necesitan más allá de la especificación base. En nuestra experiencia, un perfil bien diseñado es la diferencia entre una integración que interopera a nivel puramente técnico y una que genuinamente intercambia datos clínicos significativos con semántica correcta — el recurso base Patient u Observation es intencionalmente flexible, y es el perfil el que convierte "FHIR válido" en "válido para su intercambio".

Diseñando el Perfil: Restricciones, Cardinalidades y Must-Support

El diseño comienza identificando el recurso base (Patient, Observation, MedicationRequest) y las restricciones que el contexto realmente requiere. Tres decisiones dominan:

• Perfilado directo sobre recursos vs. modelos lógicos primero: perfilar directamente sobre recursos es más rápido; definir modelos lógicos primero mantiene los requisitos clínicos independientes de los mecanismos de FHIR y da resultado cuando el mismo modelo debe apuntar a múltiples versiones de FHIR o estándares. En nuestra experiencia, los equipos con modelos de información clínica existentes (incluyendo arquetipos openEHR) se benefician de modelar primero y mapear después.
• Agresividad de cardinalidades: cada elemento que se fuerza a 1..1 excluye a todo sistema del mundo real que no puede poblarlo de forma confiable. Restringir lo que el caso de uso exige; dejar flexibilidad al implementador en lo demás. Recordar que en FHIR, cardinalidad mínima 1 por sí sola no garantiza que haya datos útiles presentes — a menudo se necesitan invariantes FHIRPath adicionales.
• Must-support vs. obligations: en FHIR R4, marcar un elemento como mustSupport significa que las implementaciones DEBEN soportarlo "de alguna manera significativa" — pero la flag en sí no define qué significa "soporte", por lo que el perfil o IG debe explicarlo en la narrativa [3]. FHIR R5 abordó esta ambigüedad introduciendo obligations: códigos legibles por máquina adjuntos via la extensión de obligación que indican precisamente lo que un actor debe hacer (poblar, mostrar, almacenar, procesar), y la extensión está definida para que también pueda usarse con versiones anteriores de FHIR [4]. Si está creando perfiles R4 hoy, sea explícito en la narrativa sobre la semántica de must-support — las flags vagas son una de las fuentes más comunes de disputas de certificación.

Creación con FHIR Shorthand y SUSHI

FHIR Shorthand (FSH) se ha convertido en el enfoque de creación estándar: un lenguaje de dominio específico, publicado como estándar HL7 (Mixed Normative/Trial Use desde febrero de 2022), que expresa perfiles, extensiones, conjuntos de valores y sistemas de códigos en texto conciso que convive fácilmente con Git [1]. SUSHI, el compilador de referencia, traduce FSH a los StructureDefinitions JSON consumidos por validadores, servidores y el IG Publisher, y soporta FHIR R4, R4B y R5 [2]. Un perfil mínimo de Patient se ve así:

// patient-profile.fsh
Alias: $mrn-system = https://example.org/fhir/NamingSystem/mrn

Profile: AcmePatient
Parent: Patient
Id: acme-patient
Title: "ACME Patient Profile"
Description: "Patient with a mandatory MRN identifier and known name."
* identifier 1..* MS
* identifier ^slicing.discriminator.type = #value
* identifier ^slicing.discriminator.path = "system"
* identifier ^slicing.rules = #open
* identifier contains mrn 1..1 MS
* identifier[mrn].system = $mrn-system
* identifier[mrn].value 1..1
* name 1..* MS
* gender 1..1
* birthDate MS

Compilarlo con SUSHI (instalado via npm install -g fsh-sushi):

sushi .   # emite fsh-generated/resources/StructureDefinition-acme-patient.json

Por defecto SUSHI genera solo el diferencial del perfil — el conjunto de cambios que el perfil hace relativo a su padre — y deja la generación del snapshot al IG Publisher, el enfoque recomendado por el liderazgo de HL7 FHIR. El snapshot es la lista de elementos completamente resuelta: el diferencial fusionado sobre cada elemento heredado del recurso base, de modo que se sostiene solo sin necesidad del padre para ser interpretado. La distinción importa en el momento del despliegue, porque la mayoría de los servidores FHIR y validadores consumen el snapshot, no el diferencial — un StructureDefinition enviado solo con un diferencial típicamente fallará al importarlo en un servidor o herramienta de terminología. Si necesita que SUSHI produzca el snapshot directamente, sin ejecutar el IG Publisher, use la flag --snapshot (-s):

sushi build . --snapshot   # emite StructureDefinitions con un snapshot resuelto

Lo equivalente puede configurarse de forma persistente via la propiedad snapshot en sushi-config.yaml. En la práctica, dejar que el IG Publisher gestione la generación del snapshot para todo lo que se publique como IG, y recurrir a --snapshot al cargar perfiles independientes directamente en un servidor o paso de validación en CI que espere definiciones resueltas.

Validando Instancias Contra el Perfil

La implementación implica probar que cada recurso que produce el sistema es conforme. La CLI del Validador FHIR oficial (validator_cli.jar, lanzada desde el proyecto org.hl7.fhir.core) valida instancias contra un perfil y reporta violaciones con detalle a nivel de ruta — ruta del elemento, línea y columna [5]:

java -jar validator_cli.jar sample-patients/*.json \
  -version 4.0 \
  -ig fsh-generated/resources \
  -profile https://example.org/fhir/StructureDefinition/acme-patient

Más allá de la CLI, plataformas de pruebas como Inferno y Touchstone ejercitan la conformidad a nivel de API, lo que importa cuando los perfiles son parte de un programa de certificación en lugar de un contrato interno.

Un problema común es publicar perfiles que son teóricamente correctos pero computacionalmente costosos de validar en tiempo de ejecución. La validación semántica profunda — expansión de terminología, evaluación de slicing, ejecución de invariantes — tiene costo real; incluso la documentación de HAPI FHIR advierte explícitamente que las implicaciones de rendimiento de ejecutar su validador de instancias en un sistema de producción siempre merecen consideración. En nuestra experiencia, el slicing profundo con discriminadores complejos y las expansiones de grandes conjuntos de valores son los culpables habituales, y perfilar el rendimiento del validador con volúmenes de mensajes realistas pertenece a la lista de verificación de pre-producción, no al post-mortem de incidentes.

El Rol de CaboLabs

Los perfiles son un activo de gobernanza, no un entregable único: evolucionan con la regulación, las versiones de terminología y los nuevos socios comerciales, y necesitan versionado, revisión y validación de regresión como cualquier otro código. CaboLabs trabaja exactamente en esta intersección de modelado clínico e ingeniería: diseñamos e implementamos perfiles FHIR y guías de implementación, construimos pipelines de creación FSH/SUSHI con validación en CI, e integramos interfaces FHIR con persistencia clínica basada en estándares — incluyendo Atomik, nuestro repositorio de datos clínicos nativo de openEHR, para arquitecturas donde FHIR maneja la capa de intercambio y openEHR proporciona la capa de almacenamiento consultable y neutral al proveedor por debajo.

Si su equipo está creando sus primeros perfiles, desenredando la semántica de must-support para una certificación, o conectando APIs FHIR a una plataforma de datos clínicos, contáctenos en cabolabs.com — le ayudaremos a diseñar perfiles que validen limpiamente, rindan en producción y sobrevivan a su próxima versión.