Storing data

Bad clinical data that enters your repository silently is worse than data that never arrived. Once it's in, finding it is expensive. Correcting it is harder. Explaining it to an auditor is worse.

Atomik supports storing data from the REST API — external systems create data in Atomik, and Atomik enforces that every commit meets both structural and clinical correctness standards before anything is persisted.

Data could be created, modified, amended and even deleted following the openEHR specifications. More about this in the Data versioning section.

Types of data supported

Atomik supports storing data for these openEHR classes:

EHR and EHR_STATUS
FOLDER
COMPOSITION
ACTOR and ROLE
PARTY_RELATIONSHIP

Each class has it's own endpoint in the openEHR REST API to create objects individually, and there is a special endpoint to create objects in bundles, in openEHR the bundle is called CONTRIBUTION. The most common use case of a CONTRIBUTION is for creating multiple COMPOSITIONs at the same time.

EHR and EHR_STATUS

Atomik implements the openEHR REST API endpoint POST /ehr to create an EHR. When an EHR is created, it's EHR_STATUS is also created. A client system could pass an EHR_STATUS or just send an empty request to that endpoint, and Atomik will create the EHR with the given EHR_STATUS or with a default one if no EHR_STATUS is provided.

FOLDER

In openEHR, an EHR can have one root directory and any amount of FOLDERs and sub FOLDERs inside that root directory. The openEHR REST API provides the POST /directory endpoint for creating and storing a new directory inside an EHR. Then you will use the PUT /directory to modify it's structure of subfolders and items like references to COMPOSITIONs.

When a create or update happens on an EHR directory, if FOLDERs contain references to items, Atomik will check if those items exist in the repository and will retrieve an error if any items don't exist, guaranteeing the data completeness and consistency of the repository.

COMPOSITION

For creating COMPOSITIONs Atomik supports the POST /composition endpoint.

ACTOR and ROLE

Atomik implemented a demographic REST API that is not part of the current openEHR REST API specification, because openEHR doesn't support the demographic model at the API level. The demographic API proposed by Atomik takes the same principles the current openEHR API has for other objects, like COMPOSITION, and applies them to the demographic classes (PERSON, ORGANISATION, AGENT, GROUP, ROLE and PARTY_RELATIONSHIP).

To create a new ACTOR (PERSON, ORGANISATION, AGENT or GROUP), Atomik provides a POST /actor endpoint in the REST API. If you want to assign a ROLE to any of those objects, you need to add the ROLE information inside the ACTOR object and it will be stored alongside the ACTOR. There is no endpoint to create a ROLE on it's own, it should be inside an ACTOR.

Note that an ACTOR can contain many ROLEs.

PARTY_RELATIONSHIP

Since PARTY_RELATIONSHIP is also a class from the demographic model, openEHR doesn't provide API endpoints to work with relationships. Atomik provides a POST /relationship endpoint that allows a client to create relationships between two existing ACTOR objects.

Note the POST /relationship endpoint will verify if the source and target of the relationship exist in the repository, to guarantee data completeness and consistency. If any of those references don't exist, the endpoint will return an meaningful error to the client of the API.

Data validation — two gates, nothing slips through

Every write to Atomik passes two validation layers before anything is stored:

Syntactic validation — the payload must conform to the openEHR JSON or XML schema. Malformed structure is rejected immediately, before parsing begins.
Semantic validation — once parsed, the object is validated against its Operational Template (OPT), referenced in the template_id field. Values must match the constraints defined in your data model: data types, cardinalities, terminology bindings.

If either check fails, Atomik returns a developer-friendly error message that identifies exactly where the problem is — so the sending system can fix it rather than silently discarding or corrupting the record.

What this means in practice: your repository contains only data that conforms to your clinical data model. No partial records, no mistyped values slipping past, no terminology mismatches discovered six months later during a data quality audit. Garbage in, error out — not garbage in, garbage stored.

Both validation levels run on creation and modification operations, for all supported data types.