# Simplified JSON data formats for openEHR
**URL:** https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915
**Category:** ITS
**Tags:** sdt, json
**Created:** [11 August 2020 13:22 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915 "2020-08-11T13:22:21Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@thomas.beale](https://discourse.openehr.org/u/thomas.beale)
#### Post date: [11 August 2020 13:22 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/1 "2020-08-11T13:22:22Z")
For those interested, [here is a wiki page](https://openehr.atlassian.net/wiki/spaces/spec/pages/624361477/Simplified+Serial+Formats+-+Data+Types) on which we are refining so-called simplified (JSON) data formats for representing EHR data when talking through openEHR REST APIs, and maybe in other contexts.
This is likely to be relevant if you use EhrScape, EhrBase, EtherCIS among other products.
---
### Author:  [@wouterzanen](https://discourse.openehr.org/u/wouterzanen)
#### Post date: [17 August 2020 09:53 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/2 "2020-08-17T09:53:18Z")
Great, does this include both template and archetype in one json?
---
### Author:  [@thomas.beale](https://discourse.openehr.org/u/thomas.beale)
#### Post date: [17 August 2020 11:49 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/3 "2020-08-17T11:49:20Z")
The JSON ‘templates’ referred to here are close-to-runtime data instances (i.e. just need the multiple fields expanded and values filled out) of an OPT, but in this ‘compact’ JSON format which programmers seem to prefer, and which is definitely more efficient than standard JSON.
To get an idea of what this kind of JSON looks like, see the [Simplified Data Template example (the Lab one) in this draft spec](https://specifications-test.openehr.org/releases/ITS-REST/latest/simplified_data_template.html#_conceptual_approach).
That example has programmer-friendly paths, not just compressed data values, and was originally developed by Better (i.e. Marand).
Just to be clear, the wiki page being talked about here is just trying to reach agreement on ‘compact’ JSON form(s) the leaf data items. It’s a work in progress…
---
### Author:  [@ian.mcnicoll](https://discourse.openehr.org/u/ian.mcnicoll)
#### Post date: [16 November 2020 13:14 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/4 "2020-11-16T13:14:21Z")
In the stringified datatype format for DV\_CODED\_TEXT, I wonder if we need to distinguish to use cases…
1. Where the rubric/value (text) is intended to be read-only /advisory i.e the original intent of
local::at00034 | Large cuff |
or just
at00034 | Large cuff |
as Better allow in AQL and is very useful in other documentation /visualisation
1. Where the text/value/rubric is intended to be written into the data
e.g the Ocean Temple Designer shortcut for default values
local::at00034:: Large cuff
I’m not clear that we need do both variants - perhaps the context of use makes it clear??
---
### Author:  [@wouterzanen](https://discourse.openehr.org/u/wouterzanen)
#### Post date: [27 January 2021 21:26 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/5 "2021-01-27T21:26:34Z")
I had the need to look into this because we’d like to transition from the better API to the openEHR API. Currently we can only use the canonical model for compositions and as we work with partners that don’t need to know openEHR this is a barrier.
In my experience if you want to simplify, you will need to get rid of archetype id’s for the simplified model. I like the FLAT model as proposed here (flath , directory path stile JSON), however we should also offer a structured JSON for s simplified model. We need this because most JavaScript Frameworks nowadays can easily access structured JSON paths, which makes it simpler to work with.
I would very much like to help out with developing this idea (although I lack the in-depth technical knowledge). Is there a timeline for developing this further?
Gr,
Wouter
---
### Author:  [@thomas.beale](https://discourse.openehr.org/u/thomas.beale)
#### Post date: [27 January 2021 22:12 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/6 "2021-01-27T22:12:32Z")
We have created a [draft spec here](https://specifications-test.openehr.org/releases/SM/latest/serial_data_formats.html).
Your input - review / suggestions would be most welcome.
---
### Author:  [@ian.mcnicoll](https://discourse.openehr.org/u/ian.mcnicoll)
#### Post date: [28 January 2021 14:51 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/7 "2021-01-28T14:51:47Z")
The adoption of the Better FLAT format and web template by EhrBase (with some assistance from Better, I understand), gives us a clear path, to make use of this as a de-facto V0 of the draft spec Thomas pointed to.
My current dvice to clients is to use the openEHR REST API for all of the resources other than /composition - where they should use the ehrscape / ethercis endpoints which support the FLAT formats. In due course, I’m sure everyone will move to the formal V1 spec of the Simplified Data Formats but we can anticipate this will take a little time, and may well introduce breaking changes.
Note that EhrBase currently only offers FLAT not STRUCTURED but based on work down by Rob Tweed of Ripple, I am increasingly confident that there is a standard algorithm that will switch between the 2, without reference back to the web template or .opt.
---
### Author:  [@erik.sundvall](https://discourse.openehr.org/u/erik.sundvall)
#### Post date: [8 March 2021 13:20 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/8 "2021-03-08T13:20:55Z")
Can we here continue the thread regarding Simplified/Serial JSON formats and associated REST call headers and content-types/mimetypes) with input from some recent openEHR SEC discussions [Feb 22](https://openehr.atlassian.net/wiki/spaces/spec/pages/1426620460/2021-02-22+SEC+Call+notes) and [March 8](https://openehr.atlassian.net/wiki/spaces/spec/pages/1472659467/2021-03-08+SEC+Call+notes), to make it easier to include more people (in addition to the SEC)?
@birger.haarbrandt and I discussed this issue briefly (March 3) and he mentioned that we now have open sourced solutions from both Better and EHRbase that can be used as a reference to point to from specs. There is also a set of conformance [tests from Better](https://github.com/better-care/openehr-rest-tests) that they both use. Some related links follow (more details will likely be added later)…
Documentation and/or Source code from EHRbase:
- EHRBase simSDT description [2.5. Step 4: Load Data — EHRbase documentation](https://ehrbase.readthedocs.io/en/latest/02_getting_started/05_load_data/index.html)
- …
Source code from Better:
- [GitHub - better-care/web-template: WebTemplate implementation for openEHR CDR](https://github.com/better-care/web-template)
- [GitHub - better-care/web-template-tests: WebTemplate unit test suite](https://github.com/better-care/web-template-tests)
- [web-template/src/test/kotlin/care/better/platform/web/template/converter at master · better-care/web-template · GitHub](https://github.com/better-care/web-template/tree/master/src/test/kotlin/care/better/platform/web/template/converter)
- [GitHub - better-care/openehr-rest-tests: OpenEHR REST integration tests](https://github.com/better-care/openehr-rest-tests)
Documents to check for possible change points in, e.g. add references to the open source implementations/tests, update references/examples of formats and REST APIs:
- [Serial data formats](https://specifications.openehr.org/releases/SM/latest/serial_data_formats.html)
- [Simplified Data Template](https://specifications.openehr.org/releases/ITS-REST/latest/simplified_data_template.html)
- [Sim B](https://specifications.openehr.org/releases/SM/latest/simplified_im_b.html)
- [Wiki page about Simplified Serial Formats](https://openehr.atlassian.net/wiki/spaces/spec/pages/624361477/Simplified+Serial+Formats+-+Data+Types)
- The REST API specifications, see below
- …
Possible REST spec change points
- General info in [API Overview](https://specifications.openehr.org/releases/ITS-REST/latest/overview.html#design-considerations-data-representation) mime types etc. The `application/openehr.wt.flat+json` as already suggested likely works, also maybe the `application/openehr.wt.structured+json` should be added. (Any possible later version of the format could be called …wt2… etc.)
- The /composition call in [the EHR API](https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html) needs a way to add the name (ID) of the template, a suggestion is to use a HTTP header named `openEHR-TEMPLATE_ID` (named after [the corresponding class](https://specifications.openehr.org/releases/BASE/latest/base_types.html#_template_id_class) and [prefixed as other openEHR-specific headers in the REST API](https://specifications.openehr.org/releases/ITS-REST/latest/overview.html#design-considerations-http-headers)) or alternatively `openEHR-LOCATABLE.archetype_details.template_id` We might also want to add request/response examples.
- We’ll need to add a way to download “web template” representations of Operational Templates, likely under [the definitions API](https://specifications.openehr.org/releases/ITS-REST/latest/definitions.html) endpoint `/definition/template/adl1.4/{template_id}` in the REST spec. Would `application/openehr.wt+json` work? The thing returned would be the same Web template representation format you get from EHRscape [API Explorer](https://www.ehrscape.com/api-explorer.html) see image below to navigate to the right spot. [EHRbase uses the same format (documentation including pedagogical example)](https://ehrbase.readthedocs.io/en/latest/02_getting_started/05_load_data/index.html#flat-format) and it is very useful for creating user interface code/tools. You can also download templates in this format from the Archetype Designer GUI 
- Suggested by @ian.mcnicoll below: IF any of the open source implementations contains an example implementation, then `/definition/template/adl1.4/{template_id}/example` could be added with behaviour corresponding to `/rest/v1/template/{templateId}/example` in the [EHRscape EHR API](https://www.ehrscape.com/api-explorer.html) (Maybe needs to formally go into in version 1.1.\* of the REST spec since it is a new endpoint?)
- If `.../example` is added, then maybe also a call corresponding to the EHRscape `/rest/v1/template/{templateId}/fields` should be considered?
(This is a “wiki” post, so others than the original author can edit it.)
---
### Author:  [@ian.mcnicoll](https://discourse.openehr.org/u/ian.mcnicoll)
#### Post date: [8 March 2021 13:58 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/9 "2021-03-08T13:58:59Z")
The 3 pressing issues IMO are agreeing…
1. How to work with the FLAT compositions via the openEHR REST API -agree additional Content-types, agree how to carry extra parameters like templateID and commitername.
2. Add Get WebTemplate from CDR - as per Erik’s last requirement ? an Accept header?
3. Add Get ‘Example composition’ calls as part of /definition - @pablo has been doing something on this for xml and the Better /template/examples really unlocks the struggle that people have to understand what a composition object should look like.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [9 March 2021 13:45 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/10 "2021-03-09T13:45:29Z")
Corrections, additions and other small changes on Content-Type and content negotiation (in API Overview) or extra headers (in EHR Api) can be done easily as part of upcoming Release 1.0.2, as long as that is the actual reality on how the real implementation works (which I believe it is).
Similarly, to add an extra header and examples under Definitions API might be ok. But I just wonder if:
1. the WebTemplate is conceptually, from the perspective of a RESTful resources, the same as an OPT-Template or not ? …otherwise we should add a new definition type (i.e. `/definition/webtemplate/v1/{template_id}`)
2. if it is another format for an OPT, agnostic of the ADL language being used, then we should have `/definition/template/webtemplate/{template_id}`
3. if is just another representation of an OPT1.4, then perhaps only an extra header on `/definition/ad1.4/{template_id}` would work, and is doable for Release 1.0.2
Which one from the above you think is more applicable?
About an extra /example as a subresource of template is a good idea, but I would do that as part of Release 1.1.0
---
### Author:  [@ian.mcnicoll](https://discourse.openehr.org/u/ian.mcnicoll)
#### Post date: [9 March 2021 13:56 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/11 "2021-03-09T13:56:19Z")
It is directly derived from the .opt but re-formulates the content (not based on AOM) to be much easier to parse (from a third-party dev POV) and also adds the shortened path segments that the FLAT/STRUCTURED composition formats use.
> [@sebastian.iancu](#):
>
> if is just another representation of an OPT1.4, then perhaps only an extra header on `/definition/ad1.4/{template_id}` would work, and is doable for Release 1.0.2
I think it is close enough to justify just an alternative Content-Type in line with the discussions around adding support for FLAT compositions
Content-Type: `application/openehr.wt+json`
THis would work nicely with the existing xml .opt : Content-Type: `application/openehr.wt+json`
or any future JSONified .opt (pure AOM) Content-Type: `application/json` and be very consistent with the proposed approach to /composition
---
### Author:  [@erik.sundvall](https://discourse.openehr.org/u/erik.sundvall)
#### Post date: [12 March 2021 08:31 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/12 "2021-03-12T08:31:36Z")
There might be one piece missing to make openEHR web application serving easier…
Do we need to recommend (or standardize) a way to store/retrieve versioned additional resources commonly needed for serving UIs, for example form definitions (to be retrieved by form renderer components), images used as UI elements etc?
One way could be to recommend a path and pattern similar to the [GET adl2 template](https://specifications.openehr.org/releases/ITS-REST/latest/definitions.html#definitions-adl-2-template-get-1) adl2 template: `/definition/template/adl2/{template_id}/{version_pattern}`, so something like `/definition/ui/{id-of-the-component}/{version_pattern}` (and return latest version when version pattern is omitted).
Another (likely wiser) suggestion would be to _not_ reinvent the wheel and instead recommend using something already standardized for this purpose like [WebDAV](https://en.wikipedia.org/wiki/WebDAV) (or a subset of it) that is already supported by many (web) server and client products (and even naively by many operating systems). If a WebDAV recommendation is considered a good idea we could include that in the 1.0.2 release. If so, should we also recommend a URI mount point for the openEHR-related webdav-repository like `/definition/dav/` or not?
P.S.
If comparing to Better’s [EhrScape](https://www.ehrscape.com/) we are talking of storing things like the …/form API call does: 
---
### Author:  [@birger.haarbrandt](https://discourse.openehr.org/u/birger.haarbrandt)
#### Post date: [12 March 2021 08:53 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/13 "2021-03-12T08:53:50Z")
Hi Erik,
the question is if the should be the scope of the openEHR standard. From my perspective, the layer above the platform should be more losely coupled to EHR specification. Would be great to get some opinions on this first before going this route. We need to make sure that besides all the standardization we still have enough room for quick innovation and degrees of freedom.
Birger
---
### Author:  [@erik.sundvall](https://discourse.openehr.org/u/erik.sundvall)
#### Post date: [12 March 2021 09:23 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/14 "2021-03-12T09:23:06Z")
Yes, I am not at all sure we should say/recommend anything about accessing resources/files with content that is not covered by any openEHR standardization. Only asking.
(Looking deeper into for example WebDAV, the way to access a specific older version might not be super-obvious to the average developer.)
---
### Author:  [@thomas.beale](https://discourse.openehr.org/u/thomas.beale)
#### Post date: [12 March 2021 11:11 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/15 "2021-03-12T11:11:41Z")
I think the general idea of having a standard way to reference UI artefacts associated with semantic entities is worth thinking about. In Task Planning, tasks can refer to ‘form ids’ and/or ‘template ids’. The former is the one an application really wants; for now, it’s just an open string field.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [12 March 2021 14:13 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/16 "2021-03-12T14:13:52Z")
Good discussions, but let’s focus now on simplified format here, UI related things can be discussed on a separate thread.
To amend REST specs, I created [[SPECITS-57] Update info about simplified format - openEHR JIRA](https://openehr.atlassian.net/browse/SPECITS-57) and [[SPECITS-58] Add support for /example sub-resource - openEHR JIRA](https://openehr.atlassian.net/browse/SPECITS-58)
---
### Author:  [@wouterzanen](https://discourse.openehr.org/u/wouterzanen)
#### Post date: [12 March 2021 20:04 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/17 "2021-03-12T20:04:45Z")
It would be good to have these simplified formats as my experience with the better formats is very good I am happy to see this moving in that direction.
In the get template call we might consider adding a header for template language so you get the template in a certain language.
It would be perhaps a good idea to work on providing a JSON schema (under /definition) variant based on the webtemplate most information should be available in either the webtemplate or the opt.
---
### Author:  [@erik.sundvall](https://discourse.openehr.org/u/erik.sundvall)
#### Post date: [16 March 2021 05:57 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/18 "2021-03-16T05:57:21Z")
Great suggestions @wouterzanen. We’ll have to discuss with implementers (ping @birger.haarbrandt and @matijap) what goes into first vs next version. We want to avoid delays of a first version.
For language choice, do you think the standard http header [Accept-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language) would work for requests, with a [Content-Language](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language) header in the response if requested language(s) was(were) available - and returning a [`406`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406) (Not Acceptable) error code if the template was not available in (any of) the requested language(s)?
So a common use case will be that one specific language is requested and you’ll either get a response with it or a 406 error if not available. And if you don’t send any Accept-Language header in your request you get some kind of default or all languages?
Should the above language feature…
- …only be for the calls `/definition/template/adl1.4/{template_id}` and the `/definition/template/adl1.4/{template_id}/example` (and `/rest/v1/template/{templateId}/fields` if added)…
- …or also apply to (some of) the `.../composition` calls in [the EHR API](https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html)?
@wouterzanen, regarding your last suggestion about JSON schema, I guess you mean a schema defining the rules to validate instances (EHR content) of a particular (web-)template’s flat or structured data instance form? There is a mime-type [application/schema+json](https://json-schema.org/draft/2020-12/json-schema-core.html) for JSON schema but in order to separate flat, structured and future other formats without adding extra API calls we could use http [Accept](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept) headers like `application/openehr.wt.flat.schema+json` and `application/openehr.wt.structured.schema+json` in requests to the [the definitions API](https://specifications.openehr.org/releases/ITS-REST/latest/definitions.html) endpoint `/definition/template/adl1.4/{template_id}`.
Would that cover the needs?
---
### Author:  [@Sidharth\_Ramesh](https://discourse.openehr.org/u/Sidharth_Ramesh)
#### Post date: [25 March 2021 10:42 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/19 "2021-03-25T10:42:30Z")
I am still confused about which format will be considered the “default” simplified JSON format.
I see in [the wiki](https://openehr.atlassian.net/wiki/spaces/spec/pages/624361477/Simplified+Serial+Formats+-+Data+Types) that the “compact format” is preferred, but I’ve never come across any CDR offering that uses this. I think having a string only representation of the value like “[snomed\_ct(3.1)::3415004|cyanosis|]” has it’s advantages, but for most use cases it’s easier to work with Better’s flat format.
Also, is the “Preferred compact format” flattened or structured?
Also, is it possible to use flattened paths, while keeping the value as structured json like so?
```json
{
"path/obtained/by/concatenating/ids": {
"|code": "238",
"|value": "other care",
"|terminology": "openehr"
}
}
```
We definitely need to work more on the documentation for these simplified formats. Deciding which one will be the default will help a lot.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [25 March 2021 12:46 UTC](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915/20 "2021-03-25T12:46:37Z")
Trying to clear out things:
- the wiki page you indicated is not a spec, just a SEC workspace we have working on the flat-format subject, so a placeholders for thoughts, etc
- the format specs are in DEVELOPMENT state, and located here: [Simplified Data Template (SDT)](https://specifications-test.openehr.org/releases/ITS-REST/latest/simplified_data_template.html)
- these specs are also referred from latest (upcoming Release 1.0.2) of REST API specs: [Overview # alternative-data-formats](https://specifications-test.openehr.org/releases/ITS-REST/latest/overview.html#header-alternative-data-formats)
Nevertheless, documentation might not be sufficient or not clear enough - therefore we’re happy to receive feedback.
[Next page](https://discourse.openehr.org/t/simplified-json-data-formats-for-openehr/915.md?page=2)