OpenAPI schemas generated from BMM files

Implementation Platform
1

@erik.sundvall mentioned that my generator could also generate OpenAPI schemas. I’ve spent the past few hours writing a generator of OpenAPI schemas from the BMM files.

Please download the generated schemas and report what needs to be fixed:

Download OpenAPI schemas

I haven’t implemented generic classes. Anybody knows how should generic classes be described in OpenAPI?

Edit: How should multiple ancestor classes be described in OpenAPI?
Edit2: How should enumeration classes be described in OpenAPI?

p.s.
@pieter also generates OpenAPI schemas from Archie.

Here is the code of the generator if somebody is interested (it should have an .dart extension but Discourse didn’t let me upload it that way):

generate_openapi.md (8.5 KB)

4 Likes
2

Generating openAPI code is fairly straightforward, it can be done with specific OpenAPI generators if you can just output json.

Nice work. It is missing the discriminator column and its values, so that will not parse polymorphism correctly.

2 Likes
3

Thank you. I added the discriminator property.

2 Likes
4

Very cool work done in half a day @borut.jures !

Are you planning to generate JSON schema also? (For tools that prefer that?)

What about plans for simplified template-based OpenAPI/schema-files as discussed in: Separating Models from Implementation - #61 by erik.sundvall

1 Like
5

Thank you!

I believe the consensus was to go ahead with OpenAPI instead of JSON Schema.

Lets see if the OpenAPI schemas will be used. @pieterbos generated them a while back and people still weren’t using them (or are they?)

I may use SDT when a generated form will send data to a CDR.

However the code for AM model is only 115 KB and it can be executed on server & frontend. This means I probably won’t need any intermediary formats to generate JSON for the CDR. Just a bunch of generated “toJson()” methods for the models (similar to “fromJson” to read the OPT).

I don’t mind generating stuff that people will actually use.

I don’t want to spend time generating stuff people say they need but then don’t do their part to make something useful with it.

Maybe what they are asking for isn’t the best approach (see the paragraph about using AM model instead of intermediary formats above). Sometimes cleaner architecture makes applications easier to develop, maintain and upgrade.

2 Likes
6

Cool work @borut.jures a next step I get exited about would be generating OpenAPI from a template. This one is simplish and useful: Clinical Knowledge Manager
.
If you want I can create an even simpler one for e.g. the BP result we talked about with @gary.

Or an even simpler, but much less well designed one here: Microsoft OneDrive - Access files anywhere. Create docs with free Office Online.

2 Likes
7

Thank you!

Maybe I’ll do that after somebody presents what they did with OpenAPI for AM and RM models.

The generated files aren’t usable as they are at the moment. I will know when somebody is serious about using them - they will start asking questions and suggesting fixes. I’ll wait until that happens :wink:

I get excited about the approach I described in my previous post. I should focus on that :blush:

1 Like
8

The thing is that RM/AM is useful for already openEHR-savvy people creating openEHR tools and CDRs. Those that do that likely already have some kind of solution (e.g. hand coded), thus no rush and less activity seen. What is missing is modern version of the TDO/TDS/TDD approach as discussed in the thread Separating Models from Implementation - #75 by erik.sundvall.

(Of course some of the generated general RM class descriptions are usable also as e.g. data type descriptions to be included in the template specific “streamlined/flattened” approach)

1 Like
9

Yes that is certainly true for some use cases. I am not sure what you are suggesting, but if it is to use paths in a way similar to what is described on a wikipage from 2012 by @thomas.beale https://openehr.atlassian.net/wiki/spaces/spec/pages/4915205/Ocean+EhrGate+-+Composition+Builder+programming+example, then note @heath.frankel’s comment at the bottom of that page regarding what developers not familiar with openEHR thought:

image
image1036×144 12.9 KB

1 Like
10

I agree with @heath.frankel’s comment. Many attempts were made to “simplify” OPTs and “protect” developers from learning openEHR AM/RM. None made them happy.

My opinion is that if developers don’t want to familiarise themselves with the openEHR approach to data modeling, they shouldn’t keep asking the community for yet another “simplification” that would enable them to work with openEHR. Just count the number of different simplifications that are useful to their authors but are still not appealing to developers who demand such simplifications. Everything is too complicated for them. I’m afraid that any solution will be too complicated with that way of thinking.

I hope there will always be developers that are willing to spend some time learning before they start building openEHR solutions.

I attempt to skip all the intermediary XML/JSON/paths… and work directly with the model. The prerequisite to this approach is to have the AM/RM available in the frontend app. Then you can write code like:

ehrGate.CreateComposition("Lipids")

…and it will use the models built on the base of OPT to serialize the data for the COMPOSITION that can be sent to the CDR.

Here is an example toJson() method for COMPOSITION that calls toJson() for its attributes (which do the same for their attributes,… turtles all the way down):

Screenshot 2021-11-29 at 11.17.16
Screenshot 2021-11-29 at 11.17.16766×514 45.1 KB

1 Like
11

I don’t want to be disrespectful to anybody but I believe there is a minimum effort required before starting to build software. I wasn’t afraid of flying until:

“The Max has been grounded since March 2019, after some badly written software caused two crashes that killed 346 people. And while Boeing has received plenty of scrutiny for its bad code.”

Boeing 737 Software Issue

3 Likes
12

There really is. People want the power of modern aircraft, mobile telephony, AI radiology assessments and video-conferencing, while also claiming that ‘every kid should program’ and ‘anyone can build software’. Sorry, but it’s not the same software.

NB: I am talking about back-end systems here. Low-code development is something else - high-level tooling for domain and UX experts to build quality applications. THis also can’t be done by just anyone because it requires some knowledge of cognitive psychology, usability and many other things. There’s really no escape anywhere for actually learning properly what needs to be learned before trying to build things. And the learning has to start with understanding the problem space.

The reason most software fails.

Awesome work BTW @borut.jures - again!

3 Likes
13

I now tried to explain my concerns a bit more in post 77 of Separating Models from Implementation - #77 by erik.sundvall

1 Like
14

I’m guessing the minimum effort required comment was meant for me.

I was developing software that was sold to hospitals around the world nearly twenty years ago.

But I do Domain driven design, as do many others. Including Martin Fowler and Eric Evans.
https://martinfowler.com/tags/domain%20driven%20design.html

Fairly sure they, and me have spent enough time in software to decide that we think this is the best approach.

15

The comment wasn’t meant for you.
It was part of the discussion with @erik.sundvall and @joostholslag . I hope they didn’t take it personally :flushed:

I appreciate the discussion you brought to openEHR and acknowledge your experience :peace_symbol:

I have thought deeply about your recommendations and even generated requested OpenAPI schemas to help you and others that would like to use them.

3 Likes
16

What fits DDD much better is to have a single level model.

This is a crude attempt using some JSON (it’s an instance rather than definition, and not pulled through all the RM attributes, but hopefully self explanatory)
AdverseReactions.json (1.0 KB)

Coded Entry is a reusable type I introduced…

1 Like
17

Also had a look at the EHR Toolkit provided by @pablo. This is template JSON export to EHRServer, which is getting closer but still refers to RM types that I as a consumer don’t know anything about.

I could however probably write a parser for this, without having to use archie or get into ADL.

JSON EHR Server format.json (123.9 KB)

1 Like
18

That looks very verbose if you are looking for streamlined formats and a single level model. I’d guess most developers would consider the e.g. structSDT format described in Simplified Data Template (SDT) simpler to work with, see example below. It is autogenerated from templates and has sensible defaults for many use cases.

{
    "ctx": {
      "language": "en",
      "territory": "SI",
      "composer_name": "matijak_test"
    },
    "vitals": {
      "vitals": [
        {
          "body_temperature": [
            {
              "any_event": [
                {
                  "description_of_thermal_stress": [
                    "Test description of symptoms"
                  ],
                  "temperature": [
                    {
                      "|magnitude": 37.2,
                      "|unit": "°C"
                    }
                  ],
                  "symptoms": [
                    {
                      "|code": "at0.64",
                      "|value": "Chills / rigor / shivering",
                      "|terminology": "local"
                    }
                  ],
                  "time": [
                    "2014-01-22T15:18:07.339+01:00"
                  ]
                }
              ]
            }
          ]
        }
      ],
      "context": [
        {
          "setting": [
            {
              "|code": "238",
              "|value": "other care",
              "|terminology": "openehr"
            }
          ],
          "start_time": [
            "2014-01-22T15:18:07.339+01:00"
          ]
        }
      ]
    }
  }

You can play with it in e.g. https://www.ehrscape.com/api-explorer.html as shown in post 61 in Separating Models from Implementation - #61 by erik.sundvall

Also see post #12 in Separating Models from Implementation - #12 by erik.sundvall

1 Like
19

There are useful ideas in this book (which I have had for years) but they apply to reference model development, and indeed I have used some.

Trying to use this approach for a really large volatile domain doesn’t work. It can work for a constrained domain though. You might envisage treating each application, or each clinical subdomain as its own thing, and doing DDD to solve it. THe problem is that there are literally thousands of clinical data points/groups common across all those domains (vital signs, common labs, for a start), so you quickly have to get into mapping data from each separate app with its own model to a common model. How will that be represented? As 5,000 Java classes? And the data set definitions are changing all the time, so it’s a giant moving target.

Martin Fowler almost figured out the correct answer in Analysis Patterns - have a look at the diagrams with the dotted lines, to distinguish between classes representing things, and classes representing kinds of things. All he had to do was to go one step further and get out of the class model for the second category.

2 Likes
20

So, this is part of the point. We think the future is going to see EPR’s broken up into several specialised app’s working across fairly fixed domains. An app for dementia, and app for joint replacements. Ecosystem is the buzz word they usually use.

OpenEHR could provide the clinical models these apps are built on…

1 Like