openehr-sdk-go

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 12, 2026 License: MIT

README

openehr-sdk-go

CI Go Reference Go Report Card Go Version Release notes

First-party Go SDK for openEHR — covers openEHR REST 1.1.0-development, the Reference Model, AQL, ADL 1.4 OPT parsing with typed primitive constraints (REQ-100 / REQ-103), template-driven composition validation (REQ-102), template-driven RM instance synthesis (REQ-107), an OPT-driven composition builder (REQ-101), and SMART-on-openEHR auth, with Cadasto-platform extras (Datamap, MPI, Extra API, Admin, Care aggregates) shipped in the same module for v1. (OET / ADL 2 are out of v1 scope.)

Status: v0.3.0 — third v0.x minor. Pre-1.0 minors may break public API; pin to the 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@v0.3.0

Use cases

The four primary consumers:

  1. Benchmark and load tools — high-concurrency CRUD against the openEHR API; the reference CDR load harness is the first consumer.
  2. Synthetic data seeders — OPT-guided fakers driving bulk Compositions and demographic records.
  3. MCP servers — exposing openEHR operations as MCP tools for agentic clients, with token-forwarded auth.
  4. Federative API clients — fan-out over multiple openEHR backends with per-node spec pinning and partial-failure handling.

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.

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@v0.3.0
go run ./cmd/examples/canonical_json   # first building-block example (no network)

Contributors:

make help        # grouped targets (toolchain, test, lint, CI, …)
make doctor      # check host Go vs Docker fallback
make ci          # full PR gate (see docs/ci.md)
make test        # unit tests (+ codegen drift check)
make fmt         # gofmt -w -s on the tree

Go 1.25.x on the host is the fast path. If host Go is missing, build the Docker dev image once (make image-dev) and the Makefile transparently routes fmt / vet / test / build through it. See Dockerfile and docker-compose.yml.

Documentation

Reading order Doc
0 — developer onboarding docs/quick-start.md · docs/examples.md
1 — entry point for any agent AGENTS.md
2 — normative specifications (REQ / PROBE / STRAND) docs/specifications/
3 — design narrative, dependency mermaid docs/architecture.md
4 — AI agent conventions, MCP skills, example-doc maintenance docs/ai-workflow.md
5 — CI / contributor checks docs/ci.md
6 — ADRs (closed) docs/adr/
6b — landed vs planned docs/roadmap.md
7 — release log CHANGELOG.md
8 — release process + version policy docs/releases.md
9 — how to contribute CONTRIBUTING.md
10 — vulnerability reporting SECURITY.md

The source of truth for module design is the in-repo docs/specifications/ tree. Open research strands live in docs/specifications/research-strands.md until promoted ADRs land in docs/adr/.

Equivalent SDK

Cadasto's PHP SDK targets the same openEHR REST surface and the same SMART-on-openEHR conformance probe set, with an idiomatic PHP API. Cross-language parity is enforced by the shared probe set, not by source-code mirroring.

License

MIT — see LICENSE.

Directories

Path Synopsis
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.
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.
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/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/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/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/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).
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.
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:
bmm
Package bmm loads openEHR Basic Meta-Model (BMM) schemas — the P_BMM JSON files pinned under resources/bmm/ — into an in-memory model.
 Package bmm loads openEHR Basic Meta-Model (BMM) schemas — the P_BMM JSON files pinned under resources/bmm/ — into an in-memory model.
client
Package client groups REST clients per openEHR resource — each sub-package corresponds to an openEHR REST 1.1.0-development surface.
 Package client groups REST clients per openEHR resource — each sub-package corresponds to an openEHR REST 1.1.0-development surface.
client/admin
Package admin is the ITS-REST `/admin/*` client (REQ-099).
 Package admin is the ITS-REST `/admin/*` client (REQ-099).
client/definition
Package definition is the openEHR REST 1.1.0-development Definition API client.
 Package definition is the openEHR REST 1.1.0-development Definition API client.
client/demographic
Package demographic is the openEHR REST client for demographic resources: PARTY hierarchy, identities, capabilities, relationships.
 Package demographic is the openEHR REST client for demographic resources: PARTY hierarchy, identities, capabilities, relationships.
client/ehr
Package ehr is the openEHR REST client for the EHR resource and its sub-resources: Composition, Contribution, Directory, EHR_STATUS, and ItemTags.
 Package ehr is the openEHR REST client for the EHR resource and its sub-resources: Composition, Contribution, Directory, EHR_STATUS, and ItemTags.
client/ehr/composition
Package composition is the openEHR REST 1.1.0-development Composition sub-resource client.
 Package composition is the openEHR REST 1.1.0-development Composition sub-resource client.
client/ehr/contribution
Package contribution is the openEHR REST 1.1.0-development Contribution sub-resource client — multi-version atomic commits against an EHR.
 Package contribution is the openEHR REST 1.1.0-development Contribution sub-resource client — multi-version atomic commits against an EHR.
client/ehr/directory
Package directory is the openEHR REST 1.1.0-development Directory (folder hierarchy) sub-resource client.
 Package directory is the openEHR REST 1.1.0-development Directory (folder hierarchy) sub-resource client.
client/ehr/ehrstatus
Package ehrstatus is the openEHR REST 1.1.0-development EHR_STATUS sub-resource client.
 Package ehrstatus is the openEHR REST 1.1.0-development EHR_STATUS sub-resource client.
client/ehr/itemtags
Package itemtags implements openEHR REST 1.1.0 ItemTag operations via the openehr-item-tag and openehr-version-item-tag headers (REQ-059).
 Package itemtags implements openEHR REST 1.1.0 ItemTag operations via the openehr-item-tag and openehr-version-item-tag headers (REQ-059).
client/query
Package query is the openEHR REST AQL executor.
 Package query is the openEHR REST AQL executor.
client/system
Package system is the openEHR REST 1.1.0-development System API client.
 Package system is the openEHR REST 1.1.0-development System API client.
composition
Package composition is the generic, OPT-driven Composition builder (REQ-101).
 Package composition is the generic, OPT-driven Composition builder (REQ-101).
instance
Package instance synthesises an RM object graph from a compiled operational template (REQ-107).
 Package instance synthesises an RM object graph from a compiled operational template (REQ-107).
rm
Package rm models the openEHR Reference Model.
 Package rm models the openEHR Reference Model.
rm/rminfo
Package rminfo answers "what does the openEHR Reference Model declare about RM class X?" — required attributes, attribute RM types, multi-cardinality flags, and the universe of known concrete class names.
 Package rminfo answers "what does the openEHR Reference Model declare about RM class X?" — required attributes, attribute RM types, multi-cardinality flags, and the universe of known concrete class names.
rm/typereg
Package typereg holds the central type registry that maps the openEHR _type discriminator to concrete Go RM types for JSON decoding.
 Package typereg holds the central type registry that maps the openEHR _type discriminator to concrete Go RM types for JSON decoding.
serialize
Package serialize provides codecs for openEHR data: canonical JSON, canonical XML, FLAT, and STRUCTURED formats.
 Package serialize provides codecs for openEHR data: canonical JSON, canonical XML, FLAT, and STRUCTURED formats.
serialize/canjson
Package canjson implements the openEHR canonical JSON codec for the SDK's generated Reference Model types.
 Package canjson implements the openEHR canonical JSON codec for the SDK's generated Reference Model types.
serialize/canxml
Package canxml implements the openEHR canonical XML codec for the SDK's generated Reference Model types — the symmetric sibling of github.com/cadasto/openehr-sdk-go/openehr/serialize/canjson.
 Package canxml implements the openEHR canonical XML codec for the SDK's generated Reference Model types — the symmetric sibling of github.com/cadasto/openehr-sdk-go/openehr/serialize/canjson.
serialize/internal/poly
Package poly holds shared helpers for polymorphic discrimination across the canjson and canxml codecs.
 Package poly holds shared helpers for polymorphic discrimination across the canjson and canxml codecs.
template
Package template parses ADL 1.4 operational templates (OPT) into an in-memory model with openEHR path utilities.
 Package template parses ADL 1.4 operational templates (OPT) into an in-memory model with openEHR path utilities.
template/constraints
Package constraints carries the typed primitive constraint values REQ-103 attaches to leaf OPT nodes.
 Package constraints carries the typed primitive constraint values REQ-103 attaches to leaf OPT nodes.
validation
Package validation checks in-memory openEHR Reference Model artefacts against a compiled OPT and reports every issue in one pass — REQ-102.
 Package validation checks in-memory openEHR Reference Model artefacts against a compiled OPT and reports every issue in one pass — REQ-102.
validation/rmread
Package rmread reads RM attribute values by name without reflection.
 Package rmread reads RM attribute values by name without reflection.
Package sandbox provides in-memory and recorded-fixture transports that implement the same client interfaces as the production REST clients — for fast, hermetic tests of applications built on the SDK.
 Package sandbox provides in-memory and recorded-fixture transports that implement the same client interfaces as the production REST clients — for fast, hermetic tests of applications built on the SDK.
Package smart is the application-level SMART launch surface (REQ-064, REQ-067): typed LaunchContext, ID-token claim parsing, and platform principal claims.
 Package smart is the application-level SMART launch surface (REQ-064, REQ-067): typed LaunchContext, ID-token claim parsing, and platform principal claims.
discovery
Package discovery resolves the SMART-on-openEHR service catalog: fetches the SMART configuration document, validates that required services (org.openehr.rest, Cadasto extras when present) are advertised, and exposes a cached, refresh-able ServiceCatalog to the typed clients.
 Package discovery resolves the SMART-on-openEHR service catalog: fetches the SMART configuration document, validates that required services (org.openehr.rest, Cadasto extras when present) are advertised, and exposes a cached, refresh-able ServiceCatalog to the typed clients.
Package testkit provides test doubles, fluent builders, recorder/replay helpers, and conformance probes for SDK consumers and for the SDK's own test suite.
 Package testkit provides test doubles, fluent builders, recorder/replay helpers, and conformance probes for SDK consumers and for the SDK's own test suite.
fixtures
Package fixtures resolves vendored cassette paths under testkit/cassettes/.
 Package fixtures resolves vendored cassette paths under testkit/cassettes/.
probes/composition
Package compositionprobes hosts the cross-SDK conformance probes for openehr/composition/ — the OPT-driven composition builder (REQ-101).
 Package compositionprobes hosts the cross-SDK conformance probes for openehr/composition/ — the OPT-driven composition builder (REQ-101).
probes/definition
Package definitionprobes hosts the cross-SDK conformance probes for the openEHR REST Definition API (PROBE-067 today; more follow alongside ADL 2 and stored-AQL surfaces).
 Package definitionprobes hosts the cross-SDK conformance probes for the openEHR REST Definition API (PROBE-067 today; more follow alongside ADL 2 and stored-AQL surfaces).
probes/discovery
Package discoveryprobes hosts the cross-SDK conformance probes for the openEHR service-discovery layer.
 Package discoveryprobes hosts the cross-SDK conformance probes for the openEHR service-discovery layer.
probes/instance
Package instanceprobes hosts the cross-SDK conformance probes for openehr/instance/ — template-driven RM instance synthesis (REQ-107).
 Package instanceprobes hosts the cross-SDK conformance probes for openehr/instance/ — template-driven RM instance synthesis (REQ-107).
probes/serialize
Package serializeprobes hosts the cross-SDK conformance probes for the openEHR serialization codecs.
 Package serializeprobes hosts the cross-SDK conformance probes for the openEHR serialization codecs.
probes/template
Package templateprobes hosts the cross-SDK conformance probes for the openehr/template/ surface — local ADL 1.4 operational template parsing and path resolution (PROBE-022).
 Package templateprobes hosts the cross-SDK conformance probes for the openehr/template/ surface — local ADL 1.4 operational template parsing and path resolution (PROBE-022).
probes/validation
Package validationprobes hosts the cross-SDK conformance probes for openehr/validation/ — composition validation against a compiled OPT (REQ-102).
 Package validationprobes hosts the cross-SDK conformance probes for openehr/validation/ — composition validation against a compiled OPT (REQ-102).
probes/versioned
Package versionedprobes hosts the cross-SDK conformance probes for the openEHR REST versioned-write contract (REQ-054).
 Package versionedprobes hosts the cross-SDK conformance probes for the openEHR REST versioned-write contract (REQ-054).
Package transport is the HTTP client wrapper around an injected *http.Client.
 Package transport is the HTTP client wrapper around an injected *http.Client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.