openehr-sdk-go

module

v0.12.0 Latest Latest Go to latest Published: Jun 30, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/cadasto/openehr-sdk-go

Links

Open Source Insights

README ¶

openehr-sdk-go

A first-party, idiomatic Go SDK for openEHR. It lets you talk to openEHR REST CDRs, model Reference Model data in typed Go, build and validate clinical Compositions from operational templates, construct AQL, and authenticate with SMART-on-openEHR — all from one module. Cadasto-platform extras (Datamap, MPI, Extra API, Admin, Care aggregates) ride along in the same module for v1 convenience, behind a clean boundary so they can be split out later.

The SDK is openEHR-first and idiomatic Go: context.Context on every I/O call, an injected *http.Client, functional options, and generics instead of reflection. Its core building blocks — RM modeling, serialization, validation, AQL, and template parsing — are usable standalone, without constructing an authenticated client. Every behaviour traces back to an in-repo normative specification (see Spec-driven design).

Pre-1.0. Public API may change across minor releases — pin to an exact tag. See docs/releases.md for the version policy and docs/roadmap.md for the landed-vs-planned matrix.

go get github.com/cadasto/openehr-sdk-go@latest   # pre-1.0: pin an exact tag for production

Use cases

The primary consumers:

Benchmark and load tools — high-concurrency CRUD against the openEHR REST API for capacity planning.
Synthetic data seeders — OPT-guided fakers driving bulk Compositions and demographic records.
MCP servers — exposing openEHR operations as MCP tools for agentic clients, with token-forwarded auth.
Federative API clients — fan-out over multiple openEHR backends with per-node spec pinning and partial-failure handling.
openEHR SMART apps with a Go backend — server-side SMART-on-openEHR launch, token handling, and CDR calls behind a Go web or API service.

Plus building-block use cases that import a single sub-package (RM modeling, codec, validation, AQL string construction, OPT parsing) without constructing an authenticated client.

Functionality

What the SDK provides today and what's planned. The authoritative landed-vs-planned status and the REQ / PROBE identifiers live in the roadmap matrix and the REQ registry.

openEHR REST client — System, EHR, EHR_STATUS, Composition, Directory, Contribution, Query, Definition (stored AQL), and Admin operations over a versioned transport. → wire, transport
Reference Model — typed RM structs with 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; FLAT / STRUCTURED planned. → wire
Templates (ADL 1.4 OPT) — operational-template parsing with typed primitive constraints and a compiled-template foundation. → rm-modeling
Compositions — OPT-driven builder, template-driven validation, and RM-instance synthesis from a template. → wire
AQL — literal AQL wire models and result sets, fluent struct/verb builders, and static parse-and-lint. → wire
Authentication — SMART-on-openEHR (PKCE), client-credentials, JWT-bearer, and basic token sources, layered over a generic injected TokenSource. → auth
Service discovery — multi-backend service catalog with per-node spec pinning and partial-failure handling. → service-discovery
Cadasto platform extras — Datamap, MPI, Extra API, Admin, and Care aggregates, shipped in-module for v1 behind a clean cut line. → module-layout
Conformance — an openEHR wire-conformance probe suite (round-trip byte-stability, spec-correct envelopes). → conformance

OET and ADL 2 are out of v1 scope.

Quickstart

New to the SDK? Start with docs/quick-start.md and the runnable catalog in docs/examples.md.

go get github.com/cadasto/openehr-sdk-go@latest
go run ./cmd/examples/canonical_json   # first building-block example (no network)

Contributors:

make help        # grouped targets (toolchain, test, lint, CI, …)
make ci          # full PR gate (see docs/ci.md)
make test        # unit tests (+ codegen drift check)
make fmt         # gofumpt + goimports (via golangci-lint)

Toolchain setup — host Go vs. the Docker fallback — is covered in docs/quick-start.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.

Doc	Scope
docs/specifications/	Normative specs — REQ / PROBE / STRAND topic specs
docs/specifications/REQ.md	Requirement registry (index → canonical topic spec)
docs/specifications/traceability.yaml	Machine-readable REQ → package / probe / test map
docs/architecture.md	Design narrative + dependency mermaid
docs/adr/	Closed architectural decisions
docs/roadmap.md	Landed-vs-planned matrix

Open research strands live in research-strands.md until promoted ADRs land in docs/adr/.

Onboarding & process

Doc	Scope
docs/quick-start.md · docs/examples.md	Developer onboarding + runnable catalog
AGENTS.md	Entry point for coding agents
docs/ai-workflow.md	AI agent conventions, MCP skills, example-doc upkeep
docs/ci.md	CI and contributor checks
CHANGELOG.md	Release log
docs/releases.md	Release process + version policy
CONTRIBUTING.md	How to contribute
SECURITY.md	Vulnerability reporting

License

MIT — see LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
auth Package auth provides the generic TokenSource abstraction and shared OAuth2 primitives (JWKS, discovery, scope builder) used by every authenticated SDK call.	Package auth provides the generic TokenSource abstraction and shared OAuth2 primitives (JWKS, discovery, scope builder) used by every authenticated SDK call.
basic Package basic implements HTTP Basic authentication (RFC 7617) as an auth.TokenSource for openEHR REST deployments that accept a static username and password on each request.	Package basic implements HTTP Basic authentication (RFC 7617) as an auth.TokenSource for openEHR REST deployments that accept a static username and password on each request.
clientcreds Package clientcreds implements the OAuth2 Client Credentials grant (RFC 6749 § 4.4) as an auth.TokenSource — for service-to-service callers (benchmark, seeder, MCP server backend, federator) that do not run an interactive user flow.	Package clientcreds implements the OAuth2 Client Credentials grant (RFC 6749 § 4.4) as an auth.TokenSource — for service-to-service callers (benchmark, seeder, MCP server backend, federator) that do not run an interactive user flow.
introspect Package introspect provides an opt-in RFC 7662 token introspection client for SDK consumers acting as resource servers or MCP gateways.	Package introspect provides an opt-in RFC 7662 token introspection client for SDK consumers acting as resource servers or MCP gateways.
jwtbearer Package jwtbearer implements the OAuth2 JWT Bearer (RFC 7523) grant as an auth.TokenSource — for systems that already hold a signed assertion and want to exchange it for an access token without an interactive flow.	Package jwtbearer implements the OAuth2 JWT Bearer (RFC 7523) grant as an auth.TokenSource — for systems that already hold a signed assertion and want to exchange it for an access token without an interactive flow.
smart Package smart implements the SMART-on-openEHR auth provider: PKCE, authorization-code launch flow, token refresh, and JWKS rotation, returning a TokenSource compatible with the parent auth package.	Package smart implements the SMART-on-openEHR auth provider: PKCE, authorization-code launch flow, token refresh, and JWKS rotation, returning a TokenSource compatible with the parent auth package.
cadasto Package cadasto is the namespace for Cadasto-platform extras — application-specific layers shipped in the same module in v1 for adoption convenience.	Package cadasto is the namespace for Cadasto-platform extras — application-specific layers shipped in the same module in v1 for adoption convenience.
admin Package admin is the client for tenant, environment, system info, and healthcheck endpoints on a Cadasto deployment.	Package admin is the client for tenant, environment, system info, and healthcheck endpoints on a Cadasto deployment.
care Package care exposes opinionated application aggregates over EHR and Demographic resources: Patient, User, CaseLoad, CareTeam, Episode.	Package care exposes opinionated application aggregates over EHR and Demographic resources: Patient, User, CaseLoad, CareTeam, Episode.
datamap Package datamap is the client and builder for Datamap V2 — the Cadasto-specific format for resource-free read and write of clinical and demographic data across the openEHR REST API surface.	Package datamap is the client and builder for Datamap V2 — the Cadasto-specific format for resource-free read and write of clinical and demographic data across the openEHR REST API surface.
extra Package extra is the client for the Cadasto Extra API — endpoints that complement openEHR REST on a Cadasto deployment.	Package extra is the client for the Cadasto Extra API — endpoints that complement openEHR REST on a Cadasto deployment.
mpi Package mpi exposes the minimal Master Patient Index search surface — a preview shape pending the Cadasto MPI / identity resolution / trust federation research outcome.	Package mpi exposes the minimal Master Patient Index search surface — a preview shape pending the Cadasto MPI / identity resolution / trust federation research outcome.
cmd
bmmdiff command bmmdiff is a small CLI that compares two BMM JSON files and prints a human-readable "what changed" summary.	bmmdiff is a small CLI that compares two BMM JSON files and prints a human-readable "what changed" summary.
bmmgen command bmmgen is the BMM-driven code generator CLI.	bmmgen is the BMM-driven code generator CLI.
examples Package examples hosts worked, runnable example programs for each named SDK use case (benchmark, seeder, MCP server, federator).	Package examples hosts worked, runnable example programs for each named SDK use case (benchmark, seeder, MCP server, federator).
examples/aql-build command Example: build an AQL query two ways — the struct-builder and the verb-functions — and show that both emit byte-identical, canonical AQL (REQ-055, PROBE-020).	Example: build an AQL query two ways — the struct-builder and the verb-functions — and show that both emit byte-identical, canonical AQL (REQ-055, PROBE-020).
examples/aql-parse-structured command Example: parse an AQL query into the SDK-GAP-17 Tier-2 structured AST (parse.Query, REQ-113) and walk its shape.	Example: parse an AQL query into the SDK-GAP-17 Tier-2 structured AST (parse.Query, REQ-113) and walk its shape.
examples/canonical_json command Example: decode a canonical-JSON Composition cassette and print a few key fields.	Example: decode a canonical-JSON Composition cassette and print a few key fields.
examples/canxml_roundtrip command Example: JSON → struct → XML → struct → JSON round-trip.	Example: JSON → struct → XML → struct → JSON round-trip.
examples/compile-build-validate command Example: the full clinical pipeline driven entirely through PUBLIC SDK packages (REQ-111) — parse an OPT, compile it with the public openehr/templatecompile bridge, build a *rm.Composition with the REQ-101 builder, serialise it to canonical JSON, round-trip it, and validate it against the same compiled template.	Example: the full clinical pipeline driven entirely through PUBLIC SDK packages (REQ-111) — parse an OPT, compile it with the public openehr/templatecompile bridge, build a *rm.Composition with the REQ-101 builder, serialise it to canonical JSON, round-trip it, and validate it against the same compiled template.
examples/ehr_create command Example: end-to-end EHR creation against an in-process httptest server.	Example: end-to-end EHR creation against an in-process httptest server.
examples/generate-example command Example: synthesise an RM instance from a compiled OPT and emit the canonical JSON to stdout.	Example: synthesise an RM instance from a compiled OPT and emit the canonical JSON to stdout.
examples/lint-aql command Example: statically lint AQL with openehr/aql/lint and the validation.ValidateAQL bridge (REQ-109).	Example: statically lint AQL with openehr/aql/lint and the validation.ValidateAQL bridge (REQ-109).
examples/opt-parse command Example: parse an ADL 1.4 operational template (OPT) and print identity, OPT metadata, and path-resolved nodes.	Example: parse an ADL 1.4 operational template (OPT) and print identity, OPT metadata, and path-resolved nodes.
examples/primitive-validate command Example: parse a minimal OPT with a DV_QUANTITY primitive constraint, resolve a path, and call PrimitiveConstraint.Validate (REQ-103).	Example: parse a minimal OPT with a DV_QUANTITY primitive constraint, resolve a path, and call PrimitiveConstraint.Validate (REQ-103).
examples/smart-launch command Example: standalone SMART-on-openEHR launch with PKCE (public client).	Example: standalone SMART-on-openEHR launch with PKCE (public client).
examples/template-explore command Example: introspect a compiled operational template through the public REQ-111 surface — walk the templatecompile.CompiledNode tree to print the template structure (the seed of a form generator) and the addressable primitive-leaf paths (the seed of path discovery / Builder.Set targets).	Example: introspect a compiled operational template through the public REQ-111 surface — walk the templatecompile.CompiledNode tree to print the template structure (the seed of a form generator) and the addressable primitive-leaf paths (the seed of path discovery / Builder.Set targets).
examples/validate-composition command Example: parse an OPT, compile it, and validate an in-memory *rm.Composition with openehr/validation (REQ-102).	Example: parse an OPT, compile it, and validate an in-memory *rm.Composition with openehr/validation (REQ-102).
examples/validate-from-json command Example: decode canonical-JSON Composition bytes with canjson, compile vital_signs.opt, and validate (REQ-052 + REQ-102).	Example: decode canonical-JSON Composition bytes with canjson, compile vital_signs.opt, and validate (REQ-052 + REQ-102).
internal Package internal hosts implementation helpers that are explicitly excluded from the module's backwards-compatibility promises (per Go convention: anything under internal/ is invisible to external consumers).	Package internal hosts implementation helpers that are explicitly excluded from the module's backwards-compatibility promises (per Go convention: anything under internal/ is invisible to external consumers).
bmmdiff Package bmmdiff computes a structured, human-readable diff between two loaded BMM schemas.	Package bmmdiff computes a structured, human-readable diff between two loaded BMM schemas.
bmmgen Package bmmgen is the BMM-driven code generator for the SDK.	Package bmmgen is the BMM-driven code generator for the SDK.
templatecompile Package templatecompile turns a parsed OPT (openehr/template's wire representation) into a walker-friendly compiled form that the composition builder (REQ-101), validator (REQ-102), and example generator consume.	Package templatecompile turns a parsed OPT (openehr/template's wire representation) into a walker-friendly compiled form that the composition builder (REQ-101), validator (REQ-102), and example generator consume.
templatecompile/walk Package walk provides a Visitor abstraction over the compiled OPT tree produced by internal/templatecompile.Compile.	Package walk provides a Visitor abstraction over the compiled OPT tree produced by internal/templatecompile.Compile.
templatecompile/walk/templatedump Package templatedump provides reference walk.Visitor implementations: a pretty-printer that renders a compiled OPT as an indented tree, and a path collector that accumulates every node's canonical AQL path.	Package templatedump provides reference walk.Visitor implementations: a pretty-printer that renders a compiled OPT as an indented tree, and a path collector that accumulates every node's canonical AQL path.
templateinstance/rmwrite Package rmwrite writes RM attribute values by name without reflection.	Package rmwrite writes RM attribute values by name without reflection.
openehr Package openehr is a namespace marker — generic openEHR primitives live in its sub-packages (rm, serialize, validation, template, aql, composition, client).	Package openehr is a namespace marker — generic openEHR primitives live in its sub-packages (rm, serialize, validation, template, aql, composition, client).
aom/aom14 Package aom14 holds Go types generated from the openEHR Archetype Object Model 1.4 (BMM source: openehr_am_1.4.0.bmm.json + openehr_base_1.3.0.bmm.json).	Package aom14 holds Go types generated from the openEHR Archetype Object Model 1.4 (BMM source: openehr_am_1.4.0.bmm.json + openehr_base_1.3.0.bmm.json).
aql Package aql provides:	Package aql provides: