openEHR in Real Systems: Where Does It Break Down in Practice?

Implementation Tools
1

Hello everyone
I have been studying the openEHR ecosystem, especially around archetypes, templates, and CDR implementations, and one question keeps coming up when thinking about real-world deployment.
From the oretical standpoint, openEHR provides a very strong foundation for structured and semantically consistent clinical data. However, when moving from theory into production systems, I am curious about where things become challenging.
Specifically, I would love to hear your experience on a few points:

  • How do teams handle frequent schema evolution without breaking downstream integrations
  • What are the biggest bottlenecks when integrating openEHR with external systems such as legacy EMR or modern API
  • Are there specific tooling gaps today that slow down developer productivity
  • At what scale do archetype and template management start becoming difficult to maintain
    From my background in building workflow driven systems and API integrations, I see openEHR as extremely powerful, but I also suspect that operational complexity increases significantly in real deployments.
    I would really appreciate hearing from those who have worked on production systems or large-scale implementations.
    Also, if there are recommended tools or patterns that helped you overcome these challenges, I would love to explore them further.
    Looking forward to your insights.
2

Hi, are you talking about the database schema here?

3

Hi Pablo, thanks for your reply.
That’s a great clarifying question. I wasn’t referring to the physical database schema specifically, but more to the evolution at the archetype and template level, and how those changes propagate through the system.
From my understanding, one of the strengths of openEHR is that the persistence layer can remain relatively stable, while the logical models evolve. However, in real-world systems, changes to archetypes or templates can still impact:

  • API contracts and payload structures
  • Validation logic
  • Downstream consumers such as analytics pipelines or integrations
    So my question is more about how teams handle that layer of evolution in practice without introducing instability.
    For example:
  • Do teams rely on strict versioning strategies for archetypes and templates?
  • Are there common patterns for maintaining backward compatibility in APIs?
  • How do you typically coordinate changes across multiple dependent systems?
    Coming from a background in workflow-driven systems and API integrations, I’ve seen that even “non-breaking” schema changes can ripple through the system if not carefully managed.
    Would love to hear how this is typically handled in mature openEHR implementations.
    Thanks again for taking the time to respond.
4

If you think in “normal” engineering terms, you’ll have to solve all those issues, though with openEHR the actual engineering process changes for better and the “new way” gets rid of some of those challenges.

This topic is huge, so let’s focus on the schema change thing first. If you implement openEHR in a relational database, your schema should be based on the openEHR Reference Model (RM), which doesn’t change much and all changes are meant to be backwards compatible. If your schema is based on that RM, then your schema doesn’t change much either.

Then consider: all archetypes and templates are based on the RM. So any data that’s stored in the tables based on the RM will be able to be stored without problems and without any changes to the schema, even if you have all different archetypes and templates or if you add new archetypes or templates, the schema is the same, because the RM is the same.

So answering your question: changes in archetypes or templates DON’T have impact in your schema, IF the schema was designed based on the RM.

Something similar happens with the API: the API doesn’t depend on specific archetypes or templates, it depends on the RM.

Same with validation logic: the validation logic depends only on the RM, though it uses the Archetype Model (AM) as a model of constraints that apply to the RM. The AM, as the RM, doesn’t change, what changes is the specific archetype created using that model. So the validation logic is based on both, RM and AM, which don’t change. So you write the validation logic once, and with that you can validate ANY openEHR data.

About archetype versioning, in general teams rely on mayor versions, since minor version changes might not involve incompatibilities. The issue is with templates: historically operational templates where difficult to version because there was no formal way to do it, though, templates are defined locally, so that’s kind of delegated to the implementing organization. While archetypes are global and should have more strict versioning. Also there are tools to check differences between archetype versions and template versions, so it’s easy to detect problems and to evaluate if, for instance, a report that depends on template x.y.z should be updated to accommodate data from template x.y+1.0

Hope that helps!

5

Hi Pablo, thanks again for taking the time to engage on this.
To clarify a bit further, yes, my main focus is really on the logical layer rather than the physical persistence layer. What I’m trying to better understand is how teams manage the lifecycle of archetypes and templates once they are already in active use across multiple systems.
In particular, I’m interested in how mature implementations deal with situations where a template evolves but is already tightly coupled to:

API contracts that external systems depend on
Validation rules embedded in services
Downstream consumers like reporting or analytics pipelines
From my experience in workflow-driven and integration-heavy environments, even small structural changes can introduce unexpected side effects if versioning and coordination are not handled very deliberately.

So I’m curious how this is typically approached in practice:
Do teams treat archetype/template versions similarly to API versioning, with strict backward compatibility guarantees
Is there a common pattern for isolating changes, such as versioned endpoints or transformation layers
How do you usually coordinate these changes across teams and environments without slowing down delivery
I’m especially interested in any real-world patterns or tooling that have proven effective at scale, since that’s where these challenges tend to surface the most.
Appreciate your insights, this is a really valuable discussion.

6

That’s the key: system components are not tightly tied to any archetype or template. That’s the basis of the openEHR design.

7

That makes sense and I agree that decoupling is a core strength of openEHR.
My curiosity is more about the implementation layer. In practice, I often see implicit coupling reintroduced through APIs, validation logic, or external consumers that rely on fixed structures.
So even if the core model is flexible, the surrounding ecosystem can become sensitive to archetype or template changes.
Do teams usually handle this with abstraction layers or transformation services, or is it expected that consumers adapt to evolving models?
Would love your perspective on how this is managed in real-world implementations.

8

Hi, Mr Suyama!

We, openEHR Japan, are talking about such implementation and standardization every month online.

This is the seminar in this month. I am looking forward to talking about openEHR anytime with you.

Shinji Kobayashi, Chair of NPO openEHR Japan

9

Hello, @shnj.kobayashi

Thanks for your message
I wish we would have a deep discussion abut the seminar for this month.
Thanks in advance.

10

I started with the database schema because it was the first point you mentioned initially. Implementation layer and logical layer follow the same principles I explained earlier.

Again, you are thinking of the “normal” system engineering process. With openEHR you need to change that view, the design and implementation changes a lot.

As I said before, the API is defined independently of specific data, so changes in archetypes or templates don’t affect it, we have a spec for REST APIs. Same with validation logic, that is not coupled to specific archetypes because the archetypes themselves are the validation rules (archetypes = data constraint model).

You can actually test and see how some of those concepts are implemented if you try the openEHR CLI GitHub - CaboLabs/openEHR-CLI: CLI to facilitate working with openEHR artifacts · GitHub (it has an MCP so you can plug it to Claude Code).

Data validation is implemented in the SDK GitHub - CaboLabs/openEHR-SDK: Simplify openEHR implementation on Java, Groovy and other JDK languages. By www.CaboLabs.com · GitHub

11

Hi there, that clarification really helps, thank you.
I see your point now more clearly that in openEHR the API and validation are intentionally model agnostic, with archetypes acting as the constraint layer rather than something the logic depends on directly.
That’s definitely a different mindset compared to traditional system design.
I think my confusion was coming from projecting typical integration patterns onto openEHR, where structure tends to leak into APIs and services.
I’ll take a closer look at the CLI and SDK you shared to better understand how this separation is enforced in practice.
Appreciate the guidance, this is very insightful.

12

It’s OK, you need to verify your current mental model while you learn more about the “openEHR mental model”, it isn’t easy and takes time.

There are several “agnostic” things in openEHR. The easier way to describe it is: openEHR is an abstraction layer between domain knowledge and software implementation, so the software is “independent” from the data it manages (sounds crazy, I know).

Some abstractions:

  1. Archetypes are RM agnostic (you can create archetypes for your own class model, though it needs to be a class model in the object oriented sense).
  2. It’s just that most of the archetypes out there are based on the openEHR Reference Model.
  3. The Reference Model becomes the physical thing helps you manage data, though it’s abstract from domain concepts like Blood Pressure or Laboratory Study Result.
  4. Specific domain concepts are modeled using archetypes, so the archetype becomes a declarative definition of the data associated to a concept, like a data schema, but a logic one, not a physical one (it’s not tied to a specific way of persistence or processing logic, is just a definition).
  5. Templates are build up from many archetypes, it’s just like a big archetype, though archetypes are defined without a use case in mind (broad), but templates are defined with specific use case in mind and maybe for local usage only (narrow).
  6. From a template you can pick which parts of which archetypes you want to use, so it’s not like the template inherits everything from the archetype, you can remove stuff you won’t use.
  7. Validation logic is based on the base RM and on the rules described in archetypes (which is a constraint model, so it’s basically composed by rules).
  8. In archetypes you have 3 types of rules: structure (types, relationships), data (specific data constraints, ranges, codes, units of measure), and terminology (names and descriptions of things defined in the archetype).
  9. The template is composed by the same rules.
  10. Based on those rules and the base RM, you can build an abstract validation component that can actually validate any RM instance that complies with a template (set of archetypes). Change the data (== change the template) and you can use the same validation logic.
  11. A similar thing happens with persistence: persistence is based on the RM so having a new template doesn’t affect the database schema at all (if it’s well designed).
  12. You can even have a generic UI generator from templates for data entry.
  13. Also data queries are abstract and independent from where and how the data is physically stored, because queries are created based on the RM and archetypes, and that is not tied to a specific database technology.

That’s openEHR in a nutshell from the technical standpoint.

Hope that helps!

13

Hey @Cozy_Beard - this might be relevant - https://www.youtube.com/watch?v=XnbrwxIcHBA