Workflow
Compile a template, validate a Composition, and encode it without touching the network. Reach for the REST client only when you have somewhere to send the result. This page walks one path from a modelling tool to a clinical data repository (CDR) and marks which steps the SDK covers.
In the SDK shipped packages you import Outside a modelling tool or a live CDR
Outside
1. Model
Author archetypes and an operational template (OPT) in a clinical modelling
tool, then export the OPT as ADL 1.4 .opt. Authoring stays in that tool; the
SDK starts from the file you export.
In the SDK
2. Work in process
Parse the OPT and compile it, all without a network. Export Web Template JSON for FLAT paths. Build a Composition or synthesise one, then validate it against the Reference Model and the compiled template. Encode canonical JSON, canonical XML, FLAT, or STRUCTURED. Build or parse AQL and lint it.
Packages: template, templatecompile, validation, and the codecs under
serialize/. The full map is on Packages.
Parse and compile
template reads the .opt. templatecompile.Compile returns the handle the
builder, the synthesiser, the validator, and AQL lint all accept.
Check before you send
validation.ValidateComposition checks the compiled OPT's constraints and the
Reference Model's own rules in one call, and reports a defect both find once.
ValidateRM checks the Reference Model's rules alone, for data no template
governs.
Build or synthesise
composition is an OPT-driven builder. When you need synthetic data instead,
instance fills a skeleton from the compiled template.
Encode what the CDR accepts
Canonical JSON and XML, plus FLAT and STRUCTURED in both directions, driven by the exported Web Template.
In the SDK
3. Publish the template
definition.UploadTemplate sends the ADL 1.4 OPT to an openEHR REST
definition API. ADL 2 upload is deferred.
In the SDK
4. Write
Attach one auth.TokenSource: SMART-on-openEHR, client credentials, JWT
bearer, or HTTP Basic. Then create an EHR, commit a Composition, or batch
several versions through a contribution. Point the service catalog at your
ITS-REST
CDR.
In tests you have two ways to avoid a real CDR. Inject sandbox.Backend as the
client's http.RoundTripper and it answers requests in memory, with no
server at all. Or start a loopback httptest server. The examples use both.
The template, composition, query and client credentials examples run on
sandbox. The examples that create an EHR, commit a contribution or run a
SMART launch start an httptest server.
Packages: client/ehr and the providers under auth/.
In the SDK
5. Read and query
Build AQL from structs or parse it from text, then run it through
client/query. The result set is a typed model, and cells that hold RM
objects decode as RM types.
Which CDR
The REST client follows the ITS-REST Release-1.1.0 OpenAPI files kept in this repository rather than any vendor's own SDK. It can therefore point at any CDR that implements that contract. Wider interoperability work is still under way, and we publish no compatibility matrix.
make test never dials a CDR. The Live probes skip unless you set the
variables below.
The roadmap tracks the status of each target; this table says how to point the SDK at one.
| Deployment | Notes |
|---|---|
| openEHR REST | The client is written against the ITS-REST Release-1.1.0 OpenAPI files in resources/its-rest/. The SDK's pinned contract version is 1.1.0 (REQ-050). By default the discovery resolver rejects a required service that advertises a different spec_version. discovery.WithAcceptedSpecVersions replaces the accepted set, so list 1.1.0 in it to keep accepting that version. |
| Cadasto | Cadasto B.V. writes this SDK. Point the client at a Cadasto CDR the same way as any other ITS-REST base. The extra APIs under cadasto/ are listed on Packages. |
| EHRbase | Web Template export and the FLAT codec follow the EHRbase reference implementation (ADR 0014). Set OPENEHR_LIVE_EHRBASE to run the Live probes against an instance. We have run the opt-in Live snapshots against EHRbase 2.35.1 locally; they are not part of CI. |
| FerroEHR | Set OPENEHR_LIVE_FERROEHR to name the deployment and OPENEHR_LIVE_FERROEHR_BASIC to carry its user:pass credential, then run the Live probes. They are not part of CI. |
| Better Platform | There is no Live probe yet. Web Template export emits EHRbase ids (blood_pressure) rather than Better camelCase ids (bloodPressure). See ADR 0014. |
Terms on this page
| Name | What it is here |
|---|---|
| OPT | ADL 1.4 operational template (XML) from a modelling tool |
| Web Template | JSON path map the SDK exports from a compiled OPT |
| Canonical JSON / XML | openEHR ITS encodings with a _type discriminator |
| FLAT / STRUCTURED | Simplified formats, bidirectional, Web-Template-driven |
| AQL | Archetype Query Language: build, parse, lint, then execute |
| RM | Reference Model types generated from the BMM this SDK builds against |
| TokenSource | One interface for SMART, client credentials, JWT bearer, and Basic |
The import map is on Packages, and the generated API is on Go reference.