Almacenamiento de datos

Los datos clínicos incorrectos que entran silenciosamente en tu repositorio son peores que los datos que nunca llegaron. Una vez adentro, encontrarlos es costoso. Corregirlos es más difícil. Explicárselo a un auditor es peor.

Atomik soporta el almacenamiento de datos desde la API REST — los sistemas externos crean datos en Atomik, y Atomik exige que cada envío cumpla con los estándares de corrección estructural y clínica antes de que se persista nada.

Los datos pueden crearse, modificarse, enmendarse e incluso eliminarse siguiendo las especificaciones de openEHR. Más sobre esto en la sección de Versionado de datos.

Tipos de datos soportados

Atomik soporta el almacenamiento de datos para estas clases de openEHR:

  • EHR y EHR_STATUS
  • FOLDER
  • COMPOSITION
  • ACTOR y ROLE
  • PARTY_RELATIONSHIP
Cada clase tiene su propio endpoint en la API REST de openEHR para crear objetos individualmente, y hay un endpoint especial para crear objetos en lotes, que en openEHR se llama CONTRIBUTION. El caso de uso más común de una CONTRIBUTION es crear múltiples COMPOSITIONs al mismo tiempo.

EHR y EHR_STATUS

Atomik implementa el endpoint de la API REST de openEHR POST /ehr para crear un EHR. Cuando se crea un EHR, también se crea su EHR_STATUS. Un sistema cliente puede enviar un EHR_STATUS o simplemente enviar una solicitud vacía a ese endpoint, y Atomik creará el EHR con el EHR_STATUS proporcionado o con uno por defecto si no se proporciona ninguno.

FOLDER

En openEHR, un EHR puede tener un directorio raíz y cualquier cantidad de FOLDERs y sub-FOLDERs dentro de ese directorio raíz. La API REST de openEHR ofrece el endpoint POST /directory para crear y almacenar un nuevo directorio dentro de un EHR. Luego usarás PUT /directory para modificar su estructura de subcarpetas e ítems, como referencias a COMPOSITIONs.

Cuando se crea o actualiza un directorio de EHR, si los FOLDERs contienen referencias a ítems, Atomik verificará si esos ítems existen en el repositorio y devolverá un error si alguno de esos ítems no existe, garantizando la completitud y consistencia de los datos del repositorio.

COMPOSITION

Para crear COMPOSITIONs, Atomik soporta el endpoint POST /composition.

ACTOR y ROLE

Atomik implementó una API REST demográfica que no forma parte de la actual especificación de la API REST de openEHR, porque openEHR no soporta el modelo demográfico a nivel de API. La API demográfica propuesta por Atomik toma los mismos principios que la API actual de openEHR tiene para otros objetos, como COMPOSITION, y los aplica a las clases demográficas (PERSON, ORGANISATION, AGENT, GROUP, ROLE y PARTY_RELATIONSHIP).

Modelo Demográfico de openEHR

Para crear un nuevo ACTOR (PERSON, ORGANISATION, AGENT o GROUP), Atomik ofrece un endpoint POST /actor en la API REST. Si quieres asignar un ROLE a cualquiera de esos objetos, necesitas agregar la información del ROLE dentro del objeto ACTOR, y se almacenará junto con el ACTOR. No hay ningún endpoint para crear un ROLE por sí solo, debe estar dentro de un ACTOR.

Ten en cuenta que un ACTOR puede contener muchos ROLEs.

PARTY_RELATIONSHIP

Dado que PARTY_RELATIONSHIP también es una clase del modelo demográfico, openEHR no ofrece endpoints de API para trabajar con relaciones. Atomik ofrece un endpoint POST /relationship que permite a un cliente crear relaciones entre dos objetos ACTOR existentes.

Ten en cuenta que el endpoint POST /relationship verificará si el origen y el destino de la relación existen en el repositorio, para garantizar la completitud y consistencia de los datos. Si alguna de esas referencias no existe, el endpoint devolverá un error significativo al cliente de la API.

Validación de datos — dos compuertas, nada se cuela

Cada escritura en Atomik pasa por dos capas de validación antes de que se almacene nada:

  1. Validación sintáctica — el payload debe cumplir con el esquema JSON o XML de openEHR. Una estructura mal formada se rechaza de inmediato, antes de que comience el parsing.
  2. Validación semántica — una vez parseado, el objeto se valida contra su Plantilla Operacional (OPT), referenciada en el campo template_id. Los valores deben coincidir con las restricciones definidas en tu modelo de datos: tipos de datos, cardinalidades, enlaces de terminología.

Si alguna de las dos verificaciones falla, Atomik devuelve un mensaje de error orientado al desarrollador que identifica exactamente dónde está el problema — para que el sistema emisor pueda corregirlo en lugar de descartar o corromper el registro silenciosamente.

Ambos niveles de validación se ejecutan tanto en operaciones de creación como de modificación, para todos los tipos de datos soportados.