Diseñamos, perfilamos, publicamos y mantenemos guías de implementación FHIR — desde el alcance institucional de una organización hasta especificaciones nacionales y regionales — en R4 y R5, con reglas de conformidad que los implementadores pueden validar por su cuenta.
Una guía de implementación no es documentación: es el contrato de conformidad.
FHIR define recursos deliberadamente flexibles para que sirvan en cualquier país y en cualquier dominio clínico. Esa misma flexibilidad explica por qué dos sistemas «compatibles con FHIR» pueden ser incapaces de entenderse. Una guía de implementación cierra esa distancia: fija qué recursos se usan, qué elementos son obligatorios, qué terminologías aplican, qué identificadores se reconocen, cómo se busca la información y qué debe cumplir un sistema para considerarse conforme. En Meddyg construimos esas guías como especificaciones ejecutables —perfiles, ValueSets, ejemplos, reglas y pruebas publicadas como paquete instalable— y no como documentos que cada implementador interpreta a su manera.
Alcances
Dos alcances, un mismo rigor técnico
El método es el mismo. Lo que cambia es quién gobierna la especificación, cuántos implementadores dependen de ella y cuánto cuesta equivocarse.
Institucional / organizacional
Una organización y los sistemas que operan bajo su autoridad.
Nacional / regional
Una jurisdicción completa, o varios países que deben reportar bajo un mismo formato.
Quién gobierna
Institucional / organizacionalUn comité técnico interno. Los acuerdos se toman entre áreas de la misma organización: clínica, TI, calidad y seguridad de la información.
Nacional / regionalUna autoridad de salud, una mesa técnica nacional o un organismo regional, con instituciones que no se reportan entre sí y que deben converger igual.
Quién implementa
Institucional / organizacionalLos sistemas propios y los de sus proveedores directos: expediente clínico, laboratorio, imágenes, farmacia, facturación, portales de paciente.
Nacional / regionalTodo el ecosistema: instituciones públicas y privadas, proveedores de software y redes de intercambio, con niveles de madurez muy distintos entre sí.
Cómo se decide
Institucional / organizacionalCiclos cortos. Se puede iterar con los implementadores reales en la misma semana y corregir sobre casos concretos.
Nacional / regionalCiclos largos, consulta pública y revisión formal. Cada decisión de perfilado afecta a decenas de implementadores a la vez.
Cómo se publica
Institucional / organizacionalPublicación interna o en un dominio propio, con el paquete disponible para los proveedores. No requiere balotaje ni consulta externa.
Nacional / regionalPublicación formal: URLs canónicas estables, jurisdicción declarada, historial de versiones y paquete disponible en registros públicos.
Cómo se versiona
Institucional / organizacionalAlineado al calendario de releases de los sistemas de la organización, que es un calendario que la organización controla.
Nacional / regionalVersionado semántico con política de compatibilidad y períodos de transición anunciados. Romper una guía nacional cuesta años de recuperación.
Cómo se exige conformidad
Institucional / organizacionalComo cláusula contractual y criterio de aceptación: un proveedor es conforme si su implementación valida contra el paquete publicado.
Nacional / regionalComo condición de habilitación para conectarse al ecosistema, con pruebas de conformidad, ambiente de certificación y, cuando aplica, connectathons.
Quién la mantiene
Institucional / organizacionalEl equipo interno, con acompañamiento de Meddyg mientras la organización consolida su propia capacidad de perfilado.
Nacional / regionalUn proceso permanente: recepción de solicitudes de cambio, releases planificados y soporte sostenido a los implementadores.
Ambos alcances comparten el mismo pipeline técnico y los mismos artefactos de conformidad. La diferencia está en la gobernanza, en la política de versiones y en el costo de un cambio incompatible.
Metodología
Cómo construimos una guía de implementación
Siete etapas. Cada una produce artefactos que se validan y se publican, no entregables intermedios que quedan dentro de un documento.
De dónde viene la guía: las SMART Guidelines de la OMS
Una guía de implementación no nace de un documento en blanco. La OMS define una escalera de cinco niveles para bajar una norma clínica narrativa hasta software que la ejecuta y se puede probar, y una guía FHIR es exactamente el nivel L3. Cuando el dominio ya tiene un DAK publicado —el nivel L2—, sus personas, procesos, elementos de datos, indicadores y requisitos son el insumo del que parte el perfilamiento, en lugar de reconstruirlos desde cero en cada país.
Los cinco niveles
L1Narrativa: la norma tal como se publica
L2DAK: personas, procesos, elementos de datos, lógica, indicadores y requisitos
L3Legible por máquina: perfiles FHIR, terminología y lógica en CQL
L4Ejecutable: probado contra casos y datos de referencia
L5Mejora continua: la evidencia de uso retroalimenta la norma
Usamos las SMART Guidelines como marco de referencia y método de trabajo. No es un proyecto entregado a la OMS: es el modelo con el que ordenamos el trabajo cuando existe una norma clínica detrás de la guía.
01
Casos de uso y alcance
Definimos qué intercambios cubre la guía y cuáles quedan explícitamente fuera. Actores, escenarios, disparadores y el recorrido completo de cada transacción, de extremo a extremo.
Artefactos
Documento de alcance
Actores y sistemas participantes
Escenarios de intercambio
Criterios de éxito
En una guía institucional
Los casos nacen de dolores concretos: un resultado que no llega, un episodio que se duplica, un reporte que alguien arma a mano cada mes.
En una guía nacional o regional
Los casos nacen de un mandato: una norma de notificación obligatoria, un programa de salud pública o un compromiso regional de reporte.
02
Modelo de información y mapeo a FHIR
Antes de perfilar, acordamos qué significa cada dato. Modelamos la información clínica del dominio y decidimos qué recurso FHIR la representa — y cuándo la respuesta correcta es una extensión y no forzar un recurso.
Artefactos
Modelo lógico
Diccionario de datos
Mapeo dato → recurso y elemento
Registro de decisiones de diseño
En una guía institucional
El mapeo se hace contra los modelos que ya existen en los sistemas de la organización, incluidas sus particularidades históricas.
En una guía nacional o regional
El mapeo se hace contra la norma y contra el core nacional, para que la nueva guía dependa de él en lugar de redefinirlo por su cuenta.
03
Perfilado y extensiones
Restringimos los recursos a lo que el caso de uso exige: cardinalidades, must-support, slicing, tipos permitidos e invariantes expresadas en FHIRPath. Las extensiones se definen solo cuando el dato no cabe en el recurso base.
Artefactos
StructureDefinition (perfiles)
StructureDefinition (extensiones)
Invariantes FHIRPath
Convenciones de identificadores
En una guía institucional
Perfilado ajustado: se puede restringir con firmeza porque el universo de sistemas es conocido y acotado.
En una guía nacional o regional
Perfilado prudente: cada obligatoriedad deja fuera a algún implementador, así que se separa lo que se exige hoy de lo que se anuncia para el próximo release.
04
Terminología y semántica
Compartir estructuras no es compartir significado. Definimos los vocabularios de cada elemento, la fuerza del binding y las equivalencias con los códigos locales que ya están en uso.
Artefactos
CodeSystem
ValueSet
ConceptMap
Fuerza de binding por elemento
Reglas de versionado terminológico
En una guía institucional
Se resuelven las tablas de códigos propias de cada sistema y su equivalencia con el vocabulario estándar, sin obligar a reemplazarlas de inmediato.
En una guía nacional o regional
Se define quién publica y mantiene los ValueSets nacionales, y bajo qué condiciones se distribuyen los vocabularios con licencia, como SNOMED CT®.
05
Conformidad y capacidad
La guía declara qué debe poder hacer un sistema conforme: qué operaciones expone, qué búsquedas soporta, qué perfiles acepta y qué debe rechazar. Sin esto, «conforme» no es verificable por nadie.
Artefactos
CapabilityStatement
SearchParameter
OperationDefinition
Ejemplos válidos y ejemplos que deben fallar
Reglas de conformidad por actor
En una guía institucional
La conformidad se convierte en cláusula contractual y en criterio de aceptación para recibir una entrega de un proveedor.
En una guía nacional o regional
La conformidad se convierte en requisito de habilitación: sin ella, un sistema no se conecta al ecosistema.
06
Publicación
Escribimos la guía en FSH y la compilamos con SUSHI y el IG Publisher, dentro de un pipeline de integración continua que ejecuta el reporte de QA en cada cambio. La salida es un sitio navegable y un paquete instalable.
Artefactos
Fuentes FSH y sushi-config
Pipeline CI con reporte QA
Sitio publicado de la guía
Paquete FHIR versionado
URLs canónicas
En una guía institucional
Se publica en un dominio de la organización y se distribuye a los proveedores como parte de su documentación de integración.
En una guía nacional o regional
Se publica con jurisdicción declarada, historial de versiones y presencia en registros públicos, con la URL canónica como identidad permanente de cada artefacto.
07
Validación, adopción y mantenimiento
Una guía que nadie logra implementar no sirve. Validamos los ejemplos con el validador oficial, preparamos material y pruebas para los implementadores, acompañamos las primeras integraciones y dejamos abierto el ciclo de cambios.
Artefactos
Ejemplos validados
TestScript y plan de pruebas
Guía para implementadores
Proceso de solicitudes de cambio
Política de versionado
En una guía institucional
Acompañamos la primera integración real hasta que valida de punta a punta en producción, no solo en el ambiente de pruebas.
En una guía nacional o regional
Se organizan pruebas de conectividad y connectathons, y se sostiene el soporte a los implementadores durante todo el período de adopción.
Estrategia de versión
R4 y R5: la versión es una decisión de ecosistema
La pregunta correcta no es cuál versión es mejor, sino con quién necesita hablar su sistema y durante cuánto tiempo. Trabajamos en ambas y, cuando el ecosistema lo exige, sostenemos las dos a la vez.
R4
FHIR R4 · 4.0.1
La versión con la base instalada más grande.
Es la versión que implementan la mayoría de los servidores, librerías y productos comerciales que hoy están en producción.
Es la que exigen muchas licitaciones y muchas integraciones ya contratadas, que no se van a renegociar por un cambio de versión.
Buena parte del ecosistema de guías publicadas y de herramientas de prueba está construida sobre ella.
Es la elección natural cuando la guía debe funcionar contra sistemas que su organización no controla.
R5
FHIR R5 · 5.0.0
Recursos más maduros para dominios donde R4 se quedaba corto.
Recursos y elementos que en R4 resultaban insuficientes llegan más completos, lo que reduce la cantidad de extensiones propias que hay que inventar.
Es la versión sobre la que Meddyg diseñó, perfiló y publicó las guías del ecosistema de salud costarricense.
Es la elección natural cuando se define un ecosistema nuevo y se controla el calendario de los implementadores.
Conviene verificar el soporte real de la versión en los servidores y herramientas del proyecto antes de comprometerla en una especificación.
Convivencia y migración
Casi ningún ecosistema cambia de versión de un día para otro. Lo normal es que R4 y R5 convivan durante años, y esa convivencia se diseña en lugar de improvisarse.
Declarar la versión de referencia de la guía y qué versiones de FHIR acepta cada endpoint, de forma explícita y verificable.
Usar extensiones cross-version cuando un dato que solo existe en una versión debe viajar en la otra, en vez de inventar una extensión propia que nadie más entenderá.
Mantener el mapeo entre los perfiles equivalentes de cada versión, para que migrar no signifique volver a diseñar la guía.
Publicar la guía en las dos versiones cuando el ecosistema lo justifica, desde un mismo modelo de información y un mismo pipeline.
Anunciar la transición con un período de solape real, para que ningún implementador quede fuera del intercambio de un release al siguiente.
Aislar la traducción entre versiones en la capa de integración, no en cada sistema cliente, para pagar ese costo una sola vez.
Resultados
Qué recibe su organización
Todo lo necesario para que un implementador construya, valide y demuestre conformidad sin depender de una reunión con nosotros.
Paquete FHIR publicable
La guía compilada y versionada, instalable con las herramientas estándar del ecosistema.
Perfiles y extensiones
StructureDefinitions con cardinalidades, must-support, slicing e invariantes documentadas.
ValueSets y ConceptMaps
Terminologías, fuerza de binding y equivalencias entre los códigos locales y los estándares.
Ejemplos validados
Instancias que pasan el validador, incluidos casos límite y ejemplos que deben fallar.
CapabilityStatement y búsquedas
Qué expone un sistema conforme: operaciones, parámetros de búsqueda y perfiles aceptados.
Fuentes y pipeline
Repositorio con FSH, configuración e integración continua, para que la guía siga viva sin nosotros.
Política de versionado
Reglas de compatibilidad, numeración y transición entre releases de la guía.
Material para implementadores
Documentación de arranque, plan de pruebas y acompañamiento de las primeras integraciones.
Experiencia
Guías que hemos construido
Especificaciones publicadas y en uso, no ejercicios de laboratorio. Cada una define el contrato de conformidad de un intercambio que hoy ocurre.
Perfiles para el intercambio de informes de estudios de imágenes médicas.
Rol de MeddygColaboración en el diseño, perfilado y publicación.
Nacional
Notificación obligatoria, vacunas y resultados de laboratorio — EDUS/CCSS
Guía para la notificación de enfermedades de notificación obligatoria, vacunas y resultados de laboratorio. Meddyg implementó y desplegó a producción el primer servidor FHIR que recibiría estas notificaciones del EDUS/CCSS, y posteriormente de otros establecimientos de salud.
Rol de MeddygParticipación en el diseño, perfilado y publicación de la guía, e implementación de la infraestructura receptora.
Regional
Notificación regional de ESAVI
Primera guía de implementación HL7® FHIR® para la notificación regional de ESAVI (Eventos Supuestamente Atribuibles a la Vacunación e Inmunización), junto con el diseño de la infraestructura que recibiría esas notificaciones.
Rol de MeddygParte del equipo de Meddyg participó como consultor en el diseño de la guía y en el diseño e implementación de la infraestructura receptora.
Nacional
Firma digital de recursos FHIR — Banco Central de Costa Rica
Integración del formato JAdES dentro de GAUDI, la plataforma de firma digital y sellado del BCCR. No es una guía en sí misma: es exactamente el tipo de regla de conformidad —cómo se firma y cómo se verifica un recurso— que una guía debe declarar para que el no repudio sea exigible.
Rol de MeddygAsistencia técnica para que los equipos del BCCR habilitaran el firmado de recursos FHIR.
Las guías anteriores son de alcance nacional y regional. El mismo método —modelo de información, perfiles, terminología, conformidad y publicación— es el que aplicamos en guías institucionales, con ciclos más cortos y gobernanza interna.
Perfil
¿Para quién es este servicio?
El método es el mismo; lo que cambia es qué está en juego cuando la especificación queda ambigua.
Autoridades nacionales de salud
Ministerios y rectorías que deben normar cómo se reporta e intercambia la información del país. La guía convierte la norma escrita en algo verificable.
Seguridad social y redes públicas
Sistemas de cobertura nacional con muchos establecimientos y proveedores. La guía define qué se le exige a cada uno, sin negociarlo caso por caso.
Organismos regionales y programas multipaís
Iniciativas donde varios países deben reportar bajo un mismo formato sin renunciar a las particularidades de cada uno.
Redes de intercambio (HIE)
Ecosistemas que incorporan nuevos participantes y necesitan un contrato técnico repetible, en vez de un acuerdo distinto por cada conexión.
Hospitales y redes hospitalarias
Organizaciones con varios sistemas clínicos que quieren dejar de negociar el formato en cada integración nueva.
Laboratorios y centros de imágenes
Resultados e informes que deben llegar a múltiples receptores externos con la misma estructura y los mismos códigos.
Proveedores de software de salud
Productos que deben demostrar conformidad con una guía nacional, o construir la suya para ordenar la integración con sus clientes.
Autodiagnóstico
¿Reconoce alguno de estos problemas?
Decimos que somos «compatibles con FHIR», pero cada integración se negocia desde cero.
Cada proveedor interpreta el estándar a su manera y todas las interpretaciones son defendibles.
Tenemos una norma de notificación escrita en prosa y nadie sabe traducirla a estructuras.
No podemos decidir si un sistema es conforme sin que un experto revise los mensajes a mano.
Publicamos perfiles, pero no ejemplos ni pruebas que los implementadores puedan ejecutar.
Nuestra guía vive en un documento que ya no coincide con lo que hacen los sistemas.
Cada institución define sus propios códigos para el mismo concepto clínico.
Necesitamos decidir entre R4 y R5 y las opiniones internas están divididas.
Tenemos una guía en R4 y el ecosistema al que debemos conectarnos avanzó a R5.
Nadie sabe quién aprueba un cambio a la especificación ni cuándo sale la próxima versión.
Cada release de la guía rompe integraciones que ya estaban funcionando.
Un proveedor pasó la revisión y en producción envía datos que no podemos procesar.
Si alguna de estas situaciones describe su organización, una guía de implementación es la forma de convertir el acuerdo en una regla que se puede validar.
¿Necesita que «conforme» signifique algo verificable?
Una guía de implementación convierte normas y acuerdos en reglas que un sistema puede validar antes de salir a producción.
