openehr-sdk-go
A first-party Go SDK for openEHR. It covers the openEHR REST API, the Reference Model as typed Go structs, building and validating Compositions from operational templates, AQL, and SMART-on-openEHR authentication.
You don't have to take all of it. The building blocks (RM types, serialization, validation, AQL, template parsing) are plain packages with no dependency on the HTTP client or on auth. If all you need is to validate a Composition in a CI job, you import that one package and nothing else.
Everything the SDK does traces back to a specification that lives in this repository. When the code and a spec disagree, the spec wins.
It's written the way Go code usually is: every I/O call takes a context.Context, you pass in your own *http.Client, configuration is done with functional options, and RM polymorphism goes through generics and a type registry rather than reflection.
Try it
A COMPOSITION is the openEHR clinical document, and canonical JSON is how the REST API carries it. This decodes one into a typed struct and reads a few fields, with no network and no CDR involved:
var c rm.Composition
if err := canjson.Unmarshal(body, &c); err != nil {
log.Fatal(err)
}
fmt.Println(c.ArchetypeNodeID, c.Category.Value, len(c.Content))
The runnable version, cmd/examples/canonical_json, does the same against a fixture bundled with the repo, so it works straight from a clone:
$ go run ./cmd/examples/canonical_json
composition: archetype_node_id=openEHR-EHR-COMPOSITION.encounter.v1
name="body_weight"
language=nl (terminology=ISO_639-1)
territory=NL
category=event
content items=1
OK: canonical-JSON Composition decoded from body_weight.json
archetype_node_id names the archetype the document is built on, language and territory are codes with the terminology they come from, category is the composition category, and content items counts the entries the document carries. The examples catalogue has a program of this size for each SDK surface (validate a composition against a template, build and lint AQL, create an EHR through the REST client, run a SMART launch), each with a note on what to copy into your own application.
To use it in your own project, pin an exact tag. The SDK is pre-1.0, so a minor release can change the public API:
go get github.com/cadasto/[email protected]
The version policy is in releases.md, and the roadmap says what has actually landed.
Who it's for
It was built with these kinds of consumer in mind:
- Benchmark and load tools running high-concurrency CRUD against the openEHR REST API.
- Synthetic data seeders that use an OPT to drive bulk Compositions and demographic records.
- MCP servers that expose openEHR operations as tools for agentic clients, forwarding the caller's token.
- Federative API clients that fan out over several openEHR backends, with per-node spec pinning and partial-failure handling.
- SMART-on-openEHR apps with a Go backend: server-side launch, token handling, and CDR calls from a Go web or API service.
If you only need one piece (RM modeling, a codec, validation, AQL string construction, OPT parsing), you can import that package on its own.
What's in it
The roadmap and the REQ registry hold the authoritative landed-vs-planned status, with REQ and PROBE identifiers.
- openEHR REST client: System, EHR, EHR_STATUS, Composition, Directory, Contribution, Query, Definition (stored AQL), Demographic, and Admin, over a versioned transport. wire, transport
- Reference Model: typed RM structs and a central type registry, generated from pinned BMM dictionaries, plus hand-written identifier, temporal, and locatable-path helpers. rm-modeling
- Serialization: canonical JSON and XML round-trips, and bidirectional FLAT / STRUCTURED simplified-format codecs driven by a Web Template. wire
- Templates (ADL 1.4 OPT): operational-template parsing with typed primitive constraints, a compiled-template foundation, and WebTemplate JSON export for form generation. rm-modeling
- Compositions: an OPT-driven builder, template-driven validation, and RM-instance synthesis from a template. wire
- AQL: literal AQL wire models and result sets, fluent struct and verb builders, and static parse-and-lint. wire
- Authentication: SMART-on-openEHR (PKCE), client credentials, JWT bearer, and basic token sources, all over one injected
TokenSource. auth
- Service discovery: a multi-backend service catalog with per-node spec pinning. service-discovery
Getting started
Start with quick-start.md, then the runnable catalog in examples.md. quick-start covers toolchain setup, whether you have host Go or use the Docker fallback.
If you're working on the SDK itself, make help lists the grouped targets and ci.md explains the PR gate.
AI-assisted development
Much of this codebase and its documentation was written with AI coding assistants such as Claude Code and Cursor. The written specification keeps that work honest. Every change is measured against the specs in this repository and has to pass the make ci gate. Each change is also reviewed before a maintainer merges it. ai-workflow.md explains how the assistants are set up and what they must look up rather than guess. The rules for contributing with AI help, including the Assisted-by: commit trailer, are in CONTRIBUTING.md.
Documentation
Spec-driven design (SDD)
The normative source of truth and the design that realises it. When code and specs disagree, the specs win.
Open research strands live in research-strands.md until promoted ADRs land in docs/adr/.
Onboarding & process
License
The SDK is released under the MIT licence. See LICENSE.
Vendored third-party artefacts (test fixtures, openEHR specification pins, the AQL grammar) keep their upstream licences. The inventory is LICENSING.md.
