Create official spec for a FLAT (JSON) format

[ErikSundvall]

There are several non standardized implementations of "flat" openEHR RM JSON formats, that usually consist of lists of key-value pairs where the key is some kind of path. There are use-cases behind the creation of such formats and it would be good to provide a public specification of such a format.

Two of the flat formats are described at: https://github.com/ethercis/ethercis/blob/master/doc/flat%20json.md

(Please edit this issue ticket to add links to other flat-format descriptions if you know of any) Background motivation of the need of tracking these thoughts as an official issue: https://github.com/ethercis/ethercis/issues/74#issuecomment-371359396

[ErikSundvall]

Discussion starter: Personally I see most value in some natural-language-independent, AQL-path-based version along the lines of ECISFLAT described in https://github.com/ethercis/ethercis/blob/master/doc/flat%20json.md that could be used for cut&paste of paths from tools.

If we want compact language-specific, human-readable serialization, then perhaps it would be of higher priority to complete an official spec on TDS3 that is partially described at https://openehr.atlassian.net/wiki/spaces/spec/pages/30408770/Template+Data+Schema+TDS+Specification+and+associated+Template+Data+Document+TDD (maybe a JSON version of it could be derived/specified too)

[ErikSundvall]

When 1.0 of the rest spec is done, the "flat JSON format" discussion should be picked up again for version 1.1 of the REST spec. Some updates/revisions to the discussion starter above follow.

• Language independence is likely not possible when there are otherwise identical sibling nodes.
• Two versions of a flat format might actually be a good thing for different use cases
  • Full flat - showing the as canonical paths as possible (paths often found in archetype/template tools), including archetype ID's and at-codes where appropriate. Inspiration: ECISFLAT.
  • Compact flat - does it need to be dependent on some future standardized form definition or is it enough to know the template to make it compact? Inspiration: Marand's flat format
• The relevant REST calls can likely be unmodified just new content types (and formal format specifications) added in https://openehr.org/releases/ITS/latest/docs/ehr.html#design-considerations-data-representation. Some idea starters
  • Current canonical XML: application/xml
  • Current canonical JSON: application/json
  • Full flat JSON: application/openehr.flat+json
  • Compact flat: application/openehr.flat.compact+json
  • Possibly flat formats using other formalisms like XML etc could be added later like application/openehr.flat+xml
• TDS3/TDD is likely a different use case (and XML centric) that should not be mixed with this Github issue.

[sebastian-iancu]

This is taken care in abstract SM, in https://openehr.atlassian.net/browse/SPECITS-33 and https://github.com/openEHR/simplified-format-incubator