DRAFT: Archetype Authoring Tools (openEHR Tooling Overview series)

Software Program - open
, ,
1

[!warning] DRAFT - Work In Progress
This series is intended to help new openEHR community members navigate the complex world of openEHR tools. It is a work in progress and may contain inaccuracies or outdated information. Please advise the author of any amendments or corrections by replying to the Discourse topic where this is posted, ideally supplying a suggested alternative form of words.

Archetype Authoring Tools

These tools are used to create and edit archetypes from scratch or modify existing ones.

Archetype Designer (Better/Marand)
Status Current - actively recommended
Cost Free to use as a hosted service
Open source Yes - source code on GitHub under openEHR Foundation organisation
Platform Web-based (any browser)
ADL support ADL 1.4 and ADL 2 (internal representation is ADL 2)
Access tools.openehr.org/designer
Source Originally at github.com/openEHR/adl-designer (repository removed as of 2025; source was donated to the openEHR Foundation by Better/Marand)

What it is: The primary recommended tool for most people doing archetype and template work today. Originally developed by Marand (now operating as Better), it was open-sourced and donated to the openEHR Foundation. It runs entirely in the browser with no installation required.

What it does: Lets you create and edit ADL 1.4 archetypes and templates with a graphical interface. It can generate Operational Templates (OPTs) and JSON Web Templates (used by EHRbase and other platforms). It supports connecting to GitHub repositories and the CKM, so you can work against real archetype libraries.

Who should use it: Anyone starting out with openEHR modelling today. Clinicians, informaticians, and developers alike. It is cross-platform by nature and far more accessible than the legacy desktop tools.

Important note on naming confusion: There are two related things often called “Archetype Designer”:

  1. The older, open-source tool at the link above (what most people mean)
  2. The Archetype Editor (the legacy Windows desktop tool, covered below) which is sometimes loosely called “the archetype designer” in old documentation

Do not confuse them.

ADL Workbench (AWB)
Status Maintained but specialist/technical use only
Cost Free
Open source Yes (Apache 2.0)
Platform Windows, Linux
ADL support ADL 1.4, ADL 2, BMMs
Access GitHub releases
Source github.com/openEHR/adl-tools

What it is: A technical reference implementation and IDE for parsing, compiling, analysing, converting and editing archetypes. It is built directly on the reference ADL parser, which means it is authoritative for validation purposes.

What it does: Provides a full IDE-style interface for working with archetypes at a technical level, including syntax-level editing, validation against the reference model, ADL 1.4 to ADL 2 conversion, and BMM (Basic Meta-Model) inspection. It was historically used alongside the Archetype Editor by technically inclined modellers.

Who should use it: Developers building openEHR tools, people working on the ADL specification itself, or those needing strict ADL 2 validation. Not required by clinical modellers working day-to-day.

Archetype Editor (Ocean Informatics / Ocean Health Systems)
Status Legacy - still functional but no longer recommended for new work
Cost Free
Open source Yes (source on GitHub, archived)
Platform Windows only
ADL support ADL 1.4 only
Access openehr.org archetype editor page
Source github.com/openEHR/arch_ed-dotnet

What it is: For many years, the Archetype Editor was the standard tool for authoring archetypes - it is what produced the majority of archetypes currently in the CKM. It is a .NET desktop application for Windows.

What it does: Provides a graphical editor for creating and editing ADL 1.4 archetypes. It is localised into a range of languages including Danish, Farsi, German, Japanese, Russian, Spanish, and Swedish. It integrates with the old CKM workflow.

Why it is legacy: It is Windows-only, does not support ADL 2, and the Archetype Designer has superseded it for new work. Older training materials still reference it and it is still listed on the openEHR website, but the openEHR Foundation’s own documentation now points to the Archetype Designer as the primary authoring tool.

Who might still use it: Someone working through older training material, or needing to work on older Windows-only environments. Avoid for new projects.

Archetype Companion (Fellowship Project, 2025)
Status New - launched early 2026 following openEHR Fellowship 2025
Cost Free
Open source Yes
Platform Web-based
Access martinkochdesign.github.io/archetype_companion

What it is: A brand new, lightweight companion tool for openEHR modellers, developed as the output of the 2025 openEHR Fellowship under mentorship from Heather Leslie. It is explicitly not a replacement for the Archetype Designer - it is a “sidekick”.

What it does: Focuses specifically on the critical step of mapping clinical data elements to archetypes. It helps modellers search and explore the archetype ecosystem to decide what to reuse, adapt, or create, before they open a full editor. Think of it as a planning and discovery tool.

Who should use it: Anyone at the “what archetypes do I need?” stage of a project. Early feedback from the community has been enthusiastic.

LinkEHR Editor / LinkEHR Studio (Veratech)
Status Active
Cost Free download (LinkEHR Editor); LinkEHR Studio is commercial
Open source No
Platform Windows (desktop)
ADL support ADL 1.4 archetypes, .oet templates, ADL 1.4 OPTs
Access linkehr.veratech.es

What it is: A multi-model archetype editor from the Valencian research group at Universitat Politecnica de Valencia, now commercialised through Veratech. Distinguishes itself by supporting multiple reference models alongside openEHR, including ISO 13606, HL7 CDA, HL7 FHIR, and CDISC ODM.

What LinkEHR Studio adds: Data normalisation capabilities and data mapping workflows, plus the LinkEHR Model Manager for publication and governance of clinical models.

Who should use it: Organisations needing to work across multiple standards, or doing data transformation work. Less relevant if you are focused purely on openEHR.

2

I am hoping that once we’ve shown these to SPB members we’ll have a clearer idea of what tooling is available and a nice series of articles, which can be moved to perhaps a Knowledge Hub section of the forum.

@SPB you may wish to:

  • proofread and fact-check
  • supply screenshots (would suggest aim for fullscreen screenshots with ideally a 4:3 aspect ratio so they look regular)
  • suggest anything I have missed.
  • suggest alternative approaches - perhaps one Topic per ‘tool’ might be better in that we can use Tags to manage status eg: deprecated archetype java etc?

I can continue the series with

  1. Template Authoring Tools
  2. Clinical Data Repositories (CDRs)
  3. Knowledge Management and Repositories
  4. Developer Tooling - SDKs, Libraries and Extensions
  5. Query Tools, Form Builders and Clinical Decision Support
  6. Deprecated and Obsolete Tools
  7. Quick Comparison Table and Where to Get Help
3

Awesome work! I would suggest a 16:9 ratio, as it is more standard than 4:3 IMHO.

I think tagging is a good idea. The tags depend highly on the way we want to search or sort things later on. Maybe we should establish a scheme with various categories. For example:

  • lifecycle; In which state is the application. For example: beta, active, deprecated, unknown
  • addressed to; Who would be the user of this application or code (Is it ready for use or do you need an IDE and programming skills?). For example: developer, end-user, all, unknown
  • ADL version; Which ADL version does it support. For example: ADL1.4, ADL2, ADL1.4-2
  • asset; Which asset (archetype, template) does this produce/work with. For example: template, archetype
  • licence; Is it free? For example: open_source, commercial, freemium
  • programming language; If this is code, the programming language would be interesting to know. For example: java, python, c++
  • language; In which language is the application available; For example: en, de, no, ca, es
4

Hi Marcus,

This is a good overview and idea. You suggestion with adding tags sounds also useful, handy to have. It is also good to show and filter by it, a sort of multi dimensional categorization.

I also second @Martin_Koch suggestions.

About the tools itself:

  • I think AWB is not really maintained and I am not aware of active usage other then Thomas or those looking to validate RM|AM<->Archetypes. I might be wrong , but maybe worth asking the current state.
  • What about CKM, should it be on the list?
  • What about openEHR-assistant-mcp? Not really a tool like the others, not deterministic, but used in an AI agentic setup can do a lot of what the others are also doing.
5

Then there was also what I believe was the first non-Ocean editor, the LiU (Linköping University) archetype editor that made SNOMED CT bindings easier https://www.diva-portal.org/smash/get/diva2:264672/FULLTEXT01.pdf

We gave the code to openEHR but maybe it got lost in translation when moving openEHR source code projects from Subversion to Github, see @thomas.beale and me discussing at openEHR Subversion => Github move progress (By the way thanks again @marcusbaw for getting the mail archives online inside Discourse!)

I don’t think anybody would like to run the LiU archetype editor in production today, but finding the source code would be good if any developer wants an AI to look at it together with the academic paper to understand the design and perhaps reimplement some of it in some more modern form.

P.s. the last time the TermViz part of the solution was refreshed and used was around 2012-2013, see GitHub - ErikSundvall/TermViz: TermViz, terminology visualization component based on HTML5/JS and D3 · GitHub Perhaps time to revive and refine?

6

For quite strange reasons, the AWB had a lot of work done on it while I was in the US (I was not allowed to use any other tool!), so it has some new smart semantics in it, and improved OPT algorithms and so on. I am currently converting it to Kotlin. The whole BMM part is already running in Kotlin. So AWB will be EOL pretty soon.

7

I assume EOL means “end of life”? If so will this new partly Kotlin-based function appera in some other tool than AWB? Have you considered transpiling stuff from Kotlin to Javascript so that it is easy to reuse in webapps?

8

sorry yes - another anglo acronym!

The entire back-end is in Kotlin, i.e. BMM parser, builder, validator, AOM parser, builder, validator. So that part can be used in an IntelliJ plugin I have built, i.e. you see all your BMM and ADL files syntax highlighted, and you can ‘run’ and it runs the appropiate compiler.

The AWB front end is another matter. It can’t really be transpiled to anything directly because the UI model/meta-models are completely different - the modern targets are more powerful. I can expose the back-end as a language server, so there is a clear API for a front-end to talk to. But as for actually building the front-ed
 still contemplating alternatives. AWB, old as it is, does a lot of nice tricks still not available in any of the newer tools (e.g. inheritance overlaying and so on).

9

To me it really feels as though there is no over-arching organising principle bringing together openEHR tooling, and to some extent it is continuing to get worse, with dozens of individuals working (it seems to me) separately and disconnectedly to create an ever more confusing landscape. No amount of ‘beginner guides’, Knowledge Hubs, websites, or GitHub repos can herd these cats. We need some leadership.

I tried to bring together my knowledge about what is current and what isn’t, and some structured data on each. The first post in the topic is a Wiki so it can be edited by others. However, there have already been suggestions to switch to a variety of other tools.

I liked the suggestion (by @joostholslag in the other related thread) of an AwesomeList in GitHub, this might be a simple starting point for managing the information on tooling, keeping the information-curation overhead small by making each one just a single line of a list, linking to some external page. An example of this in practice is this AwesomeList: GitHub - kakoni/awesome-healthcare: Curated list of awesome open source healthcare software, libraries, tools and resources. · GitHub. If we did this, it would be called something like github.com/openehr/awesome-openehr and we would accept PRs to add info.

10

Tool and software building in the open source space has proceeded completely organically, with most tools built by various companies that decided to release specific things open source.

I spent quite a bit of time, as well as Tony Shannon whom you will remember, on the document attached here, which was circulated some years ago, but we got no traction. That’s no criticism of anyone; we probably would have hoped for some proper funding, maybe from NHS, Wellcome, a European source, or possibly big tech, to help get a more coherent approach off the ground. While there is patchy funding, there will only be patchy open source offerings.

We actually spent a lot of time thinking about how Apache works (in particular), and devised a governance structure that you will see in this document.

openEHR_software_program.pdf (390.8 KB)

More recent efforts (about 3y ago) by myself and a few others to get a Software Program Board moving did not attract much interest.

Anyway, ‘organisation’ can only come from a common roadmap that everyone more or less agrees to, and gets progressively filled in with various components, tools etc. A realist view of this would be that not everything in the roadmap has to be OS, it just has to have defined and stable interfaces.

People in the Software Program might want to revisit this document if they have not seen it.

11

Thanks @thomas.beale for posting that 2019 document. I’ve reposted it in its own topic for discussion because this topic is about Archetype Authoring Tools.

12

I would move the Archetype Companion to the “Knowledge managment” section, as you cannot author “real” archetypes with it.