Motor de Terminología FHIR Híbrido: Local + Externo

¿Qué es un Servicio de Terminología FHIR?

Los servidores de Terminology (servidores TX) son servicios FHIR especializados en la gestión de recursos de artefactos de conocimiento relacionados con la terminología y el vocabulario. Un único servidor TX puede proporcionar capacidades de operaciones de terminología para muchos servidores FHIR. Los servidores TX generalmente no gestionan recursos clínicos como pacientes, observaciones, medicamentos o informes de diagnóstico, sino recursos utilizados para integrar conocimiento en los sistemas de salud. Los servicios TX ayudan a resolver problemas como:

• «¿Es 85354-9 un código LOINC válido?» ($validate-code)
• «Dame todos los códigos para mediciones de signos vitales» ($expand)
• «¿Cuál es el nombre de presentación del código ICD-10 S920?» ($lookup)
• «¿Cuál es el equivalente en SNOMED de este diagnóstico ICD-10?» ($translate)

Los servidores TX gestionan habitualmente terminologías estándar con gran volumen de contenido, también denominadas terminologías externas. Estas terminologías presentan enormes retos de almacenamiento y mantenimiento:

• SNOMED CT International: Más de 365 000 conceptos activos con complejas relaciones jerárquicas
• LOINC: Más de 100 000 códigos de observaciones clínicas y de laboratorio con extensas propiedades
• RxNorm: Más de 200 000 conceptos de medicamentos, incluidas variaciones históricas y de marca
• ICD-10: Más de 70 000 códigos de diagnóstico en múltiples variantes nacionales

Los servidores TX también gestionan terminologías comunitarias incluidas en las Guías de Implementación (IGs), como US Core (que contiene terminología adaptada a las prácticas sanitarias de Estados Unidos), así como terminologías personalizadas propias de cada organización, representadas como CodeSystems y ValueSets locales.

El Problema

Las organizaciones que implementan FHIR necesitan una cobertura integral de terminologías externas en combinación con terminologías personalizadas y terminologías comunitarias. Raramente utilizan terminologías de forma aislada. A esto lo denominaremos el problema de las terminologías mixtas. Un despliegue típico de una historia clínica electrónica podría requerir:

resourceType: ValueSet
compose:
  include:
  - system: http://loinc.org
    filter:
    - property: SCALE_TYP
      op: "="
      value: Qn
  - system: http://example.org/fhir/CodeSystem/custom-vitals
    concept:
    - code: pain-scale-1-10
    - code: mobility-assessment
  - system: http://hl7.org/fhir/us/core/CodeSystem/us-core-category
    concept:
    - code: vital-signs

Este único ValueSet combina:

• Terminología externa (LOINC) con requisitos de filtrado
• Terminología personalizada para mediciones específicas de la organización
• Terminología comunitaria de US Core para la interoperabilidad

El enfoque tradicional para este requisito de terminologías mixtas consiste en gestionar los tres tipos de terminologías en el mismo servidor TX.

Servidores de Terminología Exclusivamente Locales y las Terminologías de Gran Tamaño

«Solo local» significa utilizar el servidor FHIR tanto para la gestión de recursos clínicos como de terminología. Este enfoque implica tratar los artefactos de conocimiento relacionados con terminologías de forma similar a los recursos clínicos, compartiendo el mismo motor, el mismo almacenamiento y la misma infraestructura.

Ventajas

• Facilidad de uso: Todo en un único lugar. No se necesitan integraciones externas ni orquestación.
• Control total: Es posible modificar los recursos de terminología de inmediato, sin esperar a actualizaciones externas.

Inconvenientes

• Gestión de datos: La gestión de terminologías externas suele requerir gigabytes de almacenamiento para definiciones de conceptos, propiedades y relaciones, incluso cuando los clientes pueden depender únicamente de un pequeño subconjunto de los conceptos de la terminología.
• Gestión del ciclo de vida: Requiere un mecanismo para mantener la terminología actualizada con las versiones oficiales.
• Escaso soporte para operaciones TX: La mayoría de los servidores FHIR no admiten completamente las funcionalidades avanzadas que ofrecen los servidores TX, por ejemplo: ValueSets implícitos, soporte para lenguajes de consulta específicos de terminología (ECL), soporte para suplementos e idiomas adicionales.

Servidores de Terminología Exclusivamente Externos y Terminologías Específicas del Contexto

Los servidores de terminología externos son servicios TX alojados que proporcionan acceso a grandes terminologías estándar sin necesidad de almacenamiento local. Entre los ejemplos se incluyen servicios comunitarios como el servidor tx de HL7 y Ontoserver, así como ofertas SaaS comerciales como Termbox de Health Samurai. Estos servicios destacan por ofrecer una cobertura completa de terminologías masivas como SNOMED CT y LOINC. Sin embargo, depender por completo de la delegación externa genera varios retos operativos, especialmente cuando una organización también necesita gestionar terminologías específicas del contexto, como las de las Guías de Implementación o los sistemas de códigos locales personalizados.

Ventajas

• Servicios TX completos: Amplia cobertura de operaciones de terminología.
• Gestión del ciclo de vida del contenido: El contenido de las terminologías externas tiene garantizada su actualización.
• Sin almacenamiento local: Use solo lo que necesite del servidor TX y de las terminologías externas, sin almacenar datos innecesarios.

Inconvenientes

• Escaso control: Los clientes no pueden aplicar actualizaciones a las terminologías; únicamente el propietario de la terminología puede ofrecer actualizaciones mediante nuevas versiones.
• Terminologías personalizadas: Dado que las terminologías mixtas son un requisito constante, es necesario tomar decisiones sobre las terminologías personalizadas: bien publicándolas en el servicio externo (poniéndolas a disposición de todos los clientes del servidor TX) o bien estableciendo algún mecanismo inteligente de enrutamiento/coordinación de las solicitudes de terminología en función de sus características.
• Mayor fragilidad: Delegar cada solicitud de terminología a un servidor TX externo hace que el sistema sea más frágil debido a la dependencia de la red y a posibles problemas de conectividad.

Tanto el enfoque exclusivamente local como el exclusivamente externo resultan insuficientes para el escenario de terminologías mixtas, obligando a asumir compromisos en funcionalidad o rendimiento. El problema central es que las terminologías con gran volumen de contenido como SNOMED CT, LOINC y RxNorm tienen una aplicabilidad amplia, mientras que las terminologías comunitarias y personalizadas son específicas del contexto y no deberían afectar a clientes de servicios de terminología no relacionados.

Resolver los retos de infraestructura de las terminologías masivas (almacenamiento, indexación, actualizaciones) requiere enfoques completamente distintos a los necesarios para gestionar vocabularios locales pequeños y en rápida evolución (agilidad, personalización, gobernanza). Los servicios TX tradicionales no pueden optimizar ambos escenarios de forma simultánea, lo que conduce a soluciones sobredimensionadas para terminología local simple o a una infraestructura inadecuada para grandes terminologías estándar.

El Enfoque Híbrido

El servicio de terminología híbrido resuelve este reto mediante el análisis inteligente de las solicitudes y la partición de las mismas. En lugar de forzar una elección binaria entre procesamiento local y externo, el motor híbrido examina cada solicitud para determinar qué recursos están disponibles localmente y cuáles requieren delegación externa, y posteriormente reensambla los resultados.

Para ilustrar el algoritmo híbrido, considere una organización sanitaria con:

• CodeSystem local: http://hl7.org/fhir/test/CodeSystem/simple
• CodeSystem remoto: http://hl7.org/fhir/sid/icd-10

Definición del CodeSystem local:

resourceType: CodeSystem
language: en
url: http://hl7.org/fhir/test/CodeSystem/simple
version: 0.1.0
hierarchyMeaning: is-a
content: complete
concept:
- code: code1
  display: Display 1

Ejemplo de Validación de Código Remoto

Validemos un código ICD-10 que requiere delegación externa.

Solicitud:

POST /fhir/ValueSet/$validate-code

resourceType: Parameters
parameter:
- name: code
  valueCode: S920
- name: system
  valueUri: http://hl7.org/fhir/sid/icd-10
- name: valueSet
  resource:
    resourceType: ValueSet
    url: http://example.org/fhir/ValueSet/vs1
    compose:
      include:
      - system: http://hl7.org/fhir/test/CodeSystem/simple
      - system: http://hl7.org/fhir/sid/icd-10

Respuesta:

resourceType: Parameters
parameter:
- name: result
  valueBoolean: true
- name: code
  valueCode: S920
- name: system
  valueUri: http://hl7.org/fhir/sid/icd-10
- name: version
  valueString: 2019-covid-expanded
- name: display
  valueString: 'Fracture of foot, except ankle : closed'

El sistema detecta que http://hl7.org/fhir/sid/icd-10 no está disponible localmente y delega la validación al servidor de terminología externo.

¿Cómo Funciona Este Motor?

El motor híbrido procesa la solicitud ValueSet/$validate-code mediante las siguientes fases:

1. Resolución del ValueSet Local y sus Dependencias

El ValueSet es el punto de entrada al contexto de ejecución de terminología. El motor híbrido resuelve el grafo completo de dependencias de forma local, incluyendo todos los CodeSystems referenciados y los ValueSets anidados.

2. Construcción del Mapa de Dependencias

Se construye un mapa de dependencias a partir de las reglas de composición del ValueSet. La resolución de dependencias se apoya en el algoritmo de resolución canónica de FHIR para seleccionar las versiones compatibles más recientes.

3. Análisis de Disponibilidad

El motor híbrido analiza el contexto de ejecución de terminología para detectar los requisitos de recursos. Este análisis examina:

• Disponibilidad del contenido del CodeSystem: Los sistemas marcados como content: "not-present" requieren procesamiento externo
• Dependencias de composición del ValueSet: Reglas de inclusión/exclusión que hacen referencia a CodeSystems no disponibles
• Resolución de URL canónicas: Recursos ausentes en el Registro de Artefactos FHIR local

4. Procesamiento con un Único Destino

Si todo está disponible localmente o todo está en remoto, la solicitud se enruta a ese único destino y se devuelve el resultado.

5. Procesamiento Híbrido

Cuando el análisis determina que partes del grafo de dependencias requieren procesamiento externo, la solicitud se ejecuta primero localmente. Si la validación local tiene éxito, el resultado se devuelve al cliente. Si falla, el motor híbrido elimina los componentes locales y delega la solicitud restante al servidor de terminología externo configurado.

Un Escenario Más Complejo: la Operación ValueSet/$expand

El algoritmo híbrido se aplica de forma similar a las operaciones $expand, con una diferencia clave: la capacidad de combinar resultados procedentes de distintas fuentes. Considere la expansión de un ValueSet que combina sistemas de terminología locales y remotos.

ValueSets disponibles localmente

resourceType: ValueSet
url: http://example.org/vs-local1
compose:
  include:
  - system: http://hl7.org/fhir/administrative-gender
    filter:
    - property: concept
      op: "="
      value: female
---
resourceType: ValueSet
url: http://example.org/vs-remote1
compose:
  include:
  - system: http://loinc.org
    filter:
    - property: concept
      op: in
      value: 1751-7,2339-0
---
resourceType: ValueSet
url: http://example.org/vs-remote2
compose:
  include:
  - system: http://loinc.org
    filter:
    - property: concept
      op: "="
      value: 2339-0

Solicitud:

POST /fhir/ValueSet/$expand

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    compose:
      include:
      - valueSet:
        - http://example.org/vs-local1
      - valueSet:
        - http://example.org/vs-remote1
      exclude:
      - valueSet:
        - http://example.org/vs-remote2

Respuesta:

resourceType: ValueSet
expansion:
  total: 2
  parameter:
  - name: used-valueset
    valueUri: http://example.org/vs-local1
  - name: used-valueset
    valueUri: http://example.org/vs-remote1
  - name: used-valueset
    valueUri: http://example.org/vs-remote2
  - name: used-codesystem
    valueUri: http://hl7.org/fhir/administrative-gender|4.0.1
  - name: used-codesystem
    valueUri: http://loinc.org|3.1.0
  - name: used-codesystem
    valueUri: http://loinc.org|2.76
  - name: version
    valueUri: http://loinc.org|2.76
  contains:
  - code: female
    system: http://hl7.org/fhir/administrative-gender
    display: Female
  - system: http://loinc.org
    code: 1751-7
    display: Albumin [Mass/volume] in Serum or Plasma

El motor híbrido procesa el concepto de administrative-gender localmente, mientras delega el filtrado de LOINC al servidor TX externo configurado. Mientras que las operaciones $validate-code requieren resultados de validación binarios, las operaciones $expand deben combinar listas de conceptos procedentes de fuentes tanto locales como remotas.

El algoritmo híbrido para las operaciones $expand incluye dos pasos adicionales:

6. ¿Se Necesitan Más Elementos?

Si la expansión local no puede satisfacer completamente la solicitud, el motor híbrido elimina los componentes locales de la solicitud original y delega las partes restantes al servidor de terminología externo configurado para resolver la expansión remota.

7. Combinación con el Resultado Local

A continuación, el motor híbrido combina las expansiones local y remota, deduplica los conceptos y produce los metadatos de expansión final con las contribuciones de ambas fuentes.

Motor de Terminología Híbrido en Aidbox

Aidbox introdujo el motor TX híbrido (TX engine) en la versión 2507, con soporte (en el momento de la publicación de este artículo) para:

• CodeSystem: operaciones $lookup y $validate-code
• ValueSet: operaciones $validate-code y $expand
• Operaciones ConceptMap: operación $translate

Consulte el registro de capacidades para más detalles.

Habilitar el Motor Híbrido en v2507+

Ejecute Aidbox localmente siguiendo la guía Ejecutar Aidbox localmente. Observe que el archivo docker-compose.yaml descargado incluye variables de entorno para habilitar el modo híbrido:

services:
  aidbox:
    environment:
      BOX_FHIR_TERMINOLOGY_ENGINE: hybrid
      BOX_FHIR_TERMINOLOGY_ENGINE_HYBRID_EXTERNAL_TX_SERVER: https://tx.health-samurai.io/fhir

Para más detalles de configuración, consulte Configuración del módulo de terminología de Aidbox.

Preparar los Recursos FHIR

Abra la Consola REST de Aidbox y envíe:

POST /fhir/ValueSet

resourceType: ValueSet
status: active
url: http://example.org/vs-local1
compose:
  include:
  - system: http://hl7.org/fhir/administrative-gender
    filter:
    - property: concept
      op: "="
      value: female

POST /fhir/ValueSet

resourceType: ValueSet
status: active
url: http://example.org/vs-remote1
compose:
  include:
  - system: http://loinc.org
    filter:
    - property: concept
      op: in
      value: 1751-7,2339-0

POST /fhir/ValueSet

resourceType: ValueSet
status: active
url: http://example.org/vs-remote2
compose:
  include:
  - system: http://loinc.org
    filter:
    - property: concept
      op: "="
      value: 2339-0

Ejecutar la Operación $expand de ValueSet

Ahora expanda un ValueSet compuesto por terminologías locales y remotas.

Solicitud:

POST /fhir/ValueSet/$expand

resourceType: Parameters
parameter:
- name: valueSet
  resource:
    resourceType: ValueSet
    compose:
      include:
      - valueSet:
        - http://example.org/vs-local1
      - valueSet:
        - http://example.org/vs-remote1
      exclude:
      - valueSet:
        - http://example.org/vs-remote2

Respuesta:

resourceType: ValueSet
expansion:
  identifier: urn:uuid:f087ced0-b9b7-4277-a4d7-e97d23ff44fe
  timestamp: '2025-09-05T14:27:07.118905554Z'
  total: 2
  parameter:
  - {name: used-valueset, valueUri: 'http://example.org/vs-local1'}
  - {name: used-valueset, valueUri: 'http://example.org/vs-remote1'}
  - {name: used-valueset, valueUri: 'http://example.org/vs-remote2'}
  - {name: used-codesystem, valueUri: 'http://hl7.org/fhir/administrative-gender|4.0.1'}
  - {name: used-codesystem, valueUri: 'http://loinc.org|2.76'}
  - {name: version, valueUri: 'http://loinc.org|2.76'}
  contains:
  - {code: female, system: 'http://hl7.org/fhir/administrative-gender', display: Female}
  - {system: 'http://loinc.org', code: 1751-7, display: 'Albumin [Mass/volume] in Serum or Plasma'}

Consulte la documentación del módulo de terminología de Aidbox para más ejemplos.

Conclusión

El motor de terminología híbrido es una solución lista para producción que aborda lo que los servicios TX tradicionales tienen dificultades para lograr: proporcionar una amplia cobertura y control local al mismo tiempo.

Principales Ventajas Frente a los Enfoques Tradicionales

• Reducción del uso de la API externa: Solo los recursos externos generan solicitudes al servidor externo.
• Procesamiento paralelo: Las consultas locales y externas pueden ejecutarse de forma concurrente.
• Caché inteligente: Los recursos locales se benefician de las optimizaciones e indexación de la base de datos, así como del almacenamiento en caché de los resultados remotos.
• Migración gradual: Mueva terminologías entre el entorno local y el externo a su propio ritmo.
• Control sobre la terminología personalizada: La terminología sensible o propietaria permanece bajo control local.
• Acceso a terminología estándar: Obtenga una cobertura integral de terminologías externas sin la carga del almacenamiento local.
• Soporte avanzado para operaciones de servidor TX: El motor híbrido implementa la especificación del servicio TX cerca del 100 % con énfasis en las terminologías personalizadas y comunitarias.

Véase también:

• Documentación del Módulo de Terminología de Aidbox
• Módulo de Terminología de Aidbox - Modo híbrido
• Aidbox FAR - CodeSystem
• Aidbox FAR - ValueSet
• Aidbox FAR - ConceptMap
• Especificación del Servicio de Terminología FHIR