Specify file format for opt2 as json schema
Description
Activity
@Joost Holslag Yes. Just delete Chapter 5. For me the primary goal of the document is “how to get to the operational template”. The main serialization format is already specified as part of ADL2.
@Borut Jures it’s fine by me. But what do we then do with the opt2 chapter 5? Just refer to adl2 spec 7.1?
@Borut Jures re json schema, they are generated from UML afaik. So only if BMM and UML are consistent, it should produce the same schema. Also there are arbitrary decision in the schema generation. I’m hoping this doesn’t have practical consequences, but I think we need more certainty than me hoping. See: https://discourse.openehr.org/t/json-schema-and-openapi-current-state-and-how-to-progress/1385?u=joostholslag
@Joost Holslag I believe that BMMs were updated with UML. Thomas uses his tool for that. But since the current versions of BMMs are already available, they are easy to update by hand and keep consistent with UML (there aren’t that many changes in the UML nowadays).
The linked thread is an additional reason to only specify the ADL format for OPT2 (although I’m not against JSON format since it is “available” automatically by serializing AOM classes).
JSON Schema and OpenAPI are great but after generating AM/RM/OPT2 in 5 different programming languages, I agree with Pieter’s comment on the thread that available code generators cannot be used. They would need to use the information found in the BMM files to generate the proper code for our needs.
@Borut Jures re ADL: I thought so too, but what should we then put under chapter 5.2.1? And re json opt2 variations, are you saying we should only specify ADL, not a json schema?
@Joost Holslag Chapter 5.2.1 is already included in https://specifications.openehr.org/releases/AM/Release-2.3.0/ADL2.html#_adl_archetype_definition_language (see artefact_type in the first code sample).
Specifying OPT2 only as ADL would require less work (specifications, conformance, testing) and provide an implementation neutral format. Today JSON is used more than XML. Tomorrow YAML or some other format might become the preferred one. JSON Schema would be required for those using JSON but there might be others who prefer XML. By specifying only ADL for OPT2 (which is already done), we avoid all these technological dependencies.
In the runtime implementation we want to avoid the dependency on ADL parser so JSON (or XML) is used and I believe that every vendor has their own ADL to JSON serializer (or there is Archie for Java or even as a CLI).
1. OPT2 is just a “normal” JSON serialization for OPERATIONAL_TEMPLATE class. The same as when ARCHETYPE or any other ADL2 class is serialized to JSON. Archie supports them the same way with Jackson annotations.
The linked JSON Schema should be OK if it follows the ADL2 BMM for OPERATIONAL_TEMPLATE.
2. I’m OK with removing the XML version.
3. ADL format is already specified since OPERATIONAL_TEMPLATE is part of the ADL2 and it doesn’t require any special handling for serialization to ADL. Any ADL serializer should be able to write it the same way as it writes archetypes.
JSON versions of OPT2 might have small differences depending on the vendor (it shouldn’t but that is the current situation). The ADL2 version of OPT2 must be valid according to the ADL2 grammar so it is stricter and usually the same for all vendors. This is why I’ve come to prefer the ADL2 version of OPT2 files. Every vendor is then free to use their own “extended” version of the JSON OPT2 in their implementation.
Details
Details
Reporter
Affects versions
Priority
High
Let’s specify the file format for opt2. https://specifications.openehr.org/releases/AM/development/OPT2.html#_file_formats
This will be very relevant since everyone will be migrating to this new format.
There’s already a json schema for opt2: https://github.com/openEHR/specifications-ITS-JSON/blob/master/components/AM/Release-2.2.0/Aom2/OPERATIONAL_TEMPLATE.json
1. Can we use that as a specification for the json (and yaml) file format?
1a Or should we use the ‘detailed’ version?
1b is this compatible with Archie?
2. I don’t think we need an XML format, can we remove that from the chapter?
3. I’m not sure we should specify an ADL format. Since opt is an implementation artefact that should be generated, not hand edited imho, I think json should be the focus. I believe Archie supports ADL opt2s. And the ADL grammar has (at least some) support for operational templates. Is this enough? Is there enough value in specifying it?
I don’t think this is a prerequisite to adl2.4 release. Since it’s not been there for 2.0-2.3.