Incompatibility issues when using Archetype Designer’s Export Fileset *.t.json files

Since a move to OPT2 is taking longer than expected I tried using *.t.json files that Better’s Archetype Designer exports (using “Export Fileset”).

I wrote a BMM file that matches the AM used in *.t.json files but also followed the standard AM definitions where they are available. Code for deserializing *.t.json files was generated from the BMM file.

Here are some notes about the incompatibilities with the specifications. It would be great if AD could implement these fixes but the main goal of posting them here is for others who would like to avoid the headaches while parsing *.t.json files.

A similar discussion produced great results for OPT2 JSON and earned some praise for teamwork (ASSERTION in openehr_expression_104.bmm is not in accordance with the specifications - #41 by DavidIngram).

A good old regular expressions were used to process the original *.t.json files:

#1 Change property names to snake_case

#2 Add “rm_type_name” and “_type” to “Interval”

From:

  "@type" : "C_REAL",
  "constraint" : [ {

To:

  "@type": "C_REAL",
  "rm_type_name": "Real",
  "constraint": [ {
    "@type": "Interval<Real>",

When there are more constraints, we cannot fix them automatically. Editing the original *.t.json is required by adding type to the second constraint.

Found in:

  • Antenatal - first visit.t.json
  • Heart Failure Clinic First Visit Summary.t.json
  "@type" : "C_INTEGER",
    "rmTypeName" : "Integer",
    "occurrences" : "1..1",
    "constraint" : [ {
      "lower" : 1,
      "upper" : 1,
      "lowerIncluded" : true,
      "upperIncluded" : true,
      "lowerUnbounded" : false,
      "upperUnbounded" : false
    }, {
      "@type": "Interval<Integer>",   <= this line was added manually
      "lower" : 2,
      "upper" : 2,
      "lowerIncluded" : true,
      "upperIncluded" : true,
      "lowerUnbounded" : false,
      "upperUnbounded" : false
    } ]

#3 Add “rm_type_name” to “C_STRING”, “C_TERMINOLOGY_CODE”,…

From:

  "@type": "C_STRING",
  "constraint": [

To:

  "@type": "C_STRING",
  "rm_type_name": "String",
  "constraint": [

#4 Add “rm_type_name” and “terminology_id” to “C_TERMINOLOGY_CODE”

Some “C_TERMINOLOGY_CODE” properties are incomplete.

From:

  "@type" : "C_TERMINOLOGY_CODE",
  "constraint" : [ "at0115" ]

To:

  "@type": "C_TERMINOLOGY_CODE",
  "rm_type_name": "CODE_PHRASE",
  "terminology_id": {
    "value": "local"
  },
  "constraint" : [ "at0115" ]

#5 Add proper “Multiplicity_interval” for the “occurrences” property

From:

  "@type": "C_COMPLEX_OBJECT",
  "rmTypeName": "ELEMENT",
  "occurrences": "0..0",

To:

  "@type": "C_COMPLEX_OBJECT",
  "rm_type_name": "ELEMENT",
  "occurrences": {
    "_type": "Multiplicity_interval",
    "lower_unbounded": false,
    "upper_unbounded": false,
    "lower_included": true,
    "upper_included": true,
    "lower": 0,
    "upper": 0
  },

#6 Extract “terminology_id” from the “value” property in “C_TERMINOLOGY_CODE”

From:

  "terminologyId": {
    "value": "local"
  },

To:

  "terminologyId": "local",

#7 Extract “lifecycle_state” from the “code_string” property in “RESOURCE_DESCRIPTION” (inside “TEMPLATE”)

From:

  "lifecycleState": {
    "codeString": "unmanaged"
  },

To:

  "lifecycleState": "local",

#8 Add “EXPR_” prefix to operator types

From:

  "@type" : "BINARY_OPERATOR",

To:

  "@type" : "EXPR_BINARY_OPERATOR",

#9 Add “_def” suffix to the “operator” property inside “BINARY_OPERATOR” and fix its type

From:

  "operator": "matches",

To:

  "operator_def": {
    "_type": "OPERATOR_DEF_BUILTIN",
    "identifier": "matches"
  },

#10 Add “is_” prefix to “differential, generated, ordered, unique”

#11 Replace “@type” with “_type”

1 Like

FYI: we are having a discussion in the SEC about not migrating ADL/TOM 1.4 to ADL2, and focus on ADL3 to merge everything, migrate and deprecate the previous specs. A final decision is not formally published but most SEC member’s opinions go in that direction.

2 Likes

Thank you Pablo. I just read the last SEC meeting notes and the ADL attachments. It is an interesting read with a mind boggling number of things to consider.

I’ll be glad to jump into ADL 3, however with OPT2 being skipped by most vendors and “propose an end of life time, like 2 years, for implementers to have time to migrate to ADL 3”, the *.t.json files will be a strong alternative for a while.

Sorry I forgot to include the link to the SEC meeting minutes.

I’m not sure I understand what you mean with:

Right now, besides NEDAP, I don’t thing any other implementer is using OPTs in ADL2.

I used OPT2 for my template-based generators, however there are no OPT2 templates. Neither CKM nor Archetype Designer exports to OPT2. I guess only Nedap has this in their CKM.

I tried to use the OPT but its data is incomplete for automated processing by my tools (I cannot find AM/RM release versions that the OPT is using,…).

The *.t.json files are the closest to OPT2 that I could find. That is why I’m trying to use them for my templated-based generators.

I didn’t know about those files, might be something from @pieterbos tools

OPT2 can be generated using the Visual Studio code openEHR extension, from templates or archetypes. It should be complete , if anything is missing I would like to know so we can fix it.
There is an Archie branch to convert OPT 1 to ADL 2 templates, but that is not yet integrated into tooling. We have a tool to create templates that we can share, if you need it.

1 Like

I found the opt_parser branch which would be a great addition to the VS Code extension.

I also found the parse_better_templates which uses *.t.json files like I’m trying to do :blush:

Your Visual Studio code openEHR extension is great and I used it to convert ADL 1.4 to ADL 2. However I’m looking for something that would convert CKM templates or Archetype Designer templates into OPT2.

As a developer I don’t mind using VS Code extension to convert files. However for the users it would be great to have the tools they are using export the templates in a standard openEHR format.

By a standard format I mean using AM as found in the specifications. For AM 2 the BMM files exist. For AM 1.4 the official BMM files don’t exist and there are as many interpretations as there are vendors. This is not good for the openEHR ecosystem.

I used Nedap’s AM/Release-2.0.6/openEHR_aom_206-generated.bmm as a starting point for the AM used by the Archetype Designer. Only a few changes were needed to match the structure of *.t.json files. Can we work together with Better (and others who are interested) to prepare an official AM 1.4 BMM file?