# OpenAPI schemas generated from BMM files **Category:** [Platform](https://discourse.openehr.org/c/platform-implem/7) **Created:** 2021-11-26 12:54 UTC **Views:** 2012 **Replies:** 26 **URL:** https://discourse.openehr.org/t/openapi-schemas-generated-from-bmm-files/2116 --- ## Post #1 by @borut.jures @erik.sundvall [mentioned](https://discourse.openehr.org/t/separating-models-from-implementation/2093/61) 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](https://neoehr.com/openehr/openapi) 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](https://discourse.openehr.org/t/implementing-bmm-in-other-languages/1043/15). --- 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|attachment](upload://mw0FKXAReWkyk971PJyQ2ZkBV92.md) (8.5 KB) --- ## Post #2 by @pieterbos Generating openAPI code is fairly straightforward, it can be done with specific OpenAPI generators if you can just output json. [quote="borut.jures, post:1, topic:2116"] Please download the generated schemas and report what needs to be fixed: [/quote] Nice work. It is missing the discriminator column and its values, so that will not parse polymorphism correctly. --- ## Post #3 by @borut.jures [quote="pieterbos, post:2, topic:2116"] It is missing the discriminator column and its values, so that will not parse polymorphism correctly. [/quote] Thank you. I added the discriminator property. --- ## Post #4 by @erik.sundvall 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: https://discourse.openehr.org/t/separating-models-from-implementation/2093/61?u=erik.sundvall --- ## Post #5 by @borut.jures [quote="erik.sundvall, post:4, topic:2116"] Very cool work done in half a day @borut.jures ! [/quote] Thank you! [quote="erik.sundvall, post:4, topic:2116"] Are you planning to generate JSON schema also? (For tools that prefer that?) [/quote] I believe the consensus was to [go ahead with OpenAPI instead of JSON Schema](https://discourse.openehr.org/t/json-schema-and-openapi-current-state-and-how-to-progress/1385). 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?) [quote="erik.sundvall, post:4, topic:2116"] What about plans for simplified template-based OpenAPI/schema-files [/quote] 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. --- ## Post #6 by @joostholslag Cool work @borut.jures a next step I get exited about would be generating OpenAPI from a template. This one is simplish and useful: https://ckm.openehr.org/ckm/templates/1013.26.380 . 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: https://1drv.ms/u/s!AnHubNL5DffCgssSUOewABP2W6mdBA?e=aq9SU5 --- ## Post #7 by @borut.jures Thank you! [quote="joostholslag, post:6, topic:2116"] a next step I get exited about would be generating OpenAPI from a template [/quote] 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: --- ## Post #8 by @erik.sundvall [quote="borut.jures, post:7, topic:2116"] 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. [/quote] 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 https://discourse.openehr.org/t/separating-models-from-implementation/2093/75. (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) --- ## Post #9 by @erik.sundvall [quote="borut.jures, post:5, topic:2116"] 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. [/quote] 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|690x95](upload://uLGOgsen0B2j4qkqxkGxfHDn5sz.png) --- ## Post #10 by @borut.jures [quote="erik.sundvall, post:8, topic:2116"] What is missing [/quote] 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. [quote="erik.sundvall, post:9, topic:2116"] I am not sure what you are suggesting [/quote] 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](https://en.wikipedia.org/wiki/Turtles_all_the_way_down)): ![Screenshot 2021-11-29 at 11.17.16|690x463, 50%](upload://vJlqrkP0WoxzgKr28t4LVYjurxN.png) --- ## Post #11 by @borut.jures 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](https://www.google.com/search?q=boeing+737+max+software+issue) --- ## Post #12 by @thomas.beale [quote="borut.jures, post:11, topic:2116"] I don’t want to be disrespectful to anybody but I believe there is a minimum effort required before starting to build software [/quote] 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](https://wolandscat.net/2013/09/29/the-real-reason-most-software-fails/). Awesome work BTW @borut.jures - again! --- ## Post #13 by @erik.sundvall [quote="borut.jures, post:11, topic:2116"] there is a minimum effort required before starting to build software [/quote] I now tried to explain my concerns a bit more in post 77 of https://discourse.openehr.org/t/separating-models-from-implementation/2093/77?u=erik.sundvall --- ## Post #14 by @ToStupidForOpenEHR 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 https://www.domainlanguage.com/ Fairly sure they, and me have spent enough time in software to decide that we think this is the best approach. --- ## Post #15 by @borut.jures [quote="ToStupidForOpenEHR, post:14, topic:2116"] I’m guessing the minimum effort required comment was meant for me. [/quote] 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. --- ## Post #16 by @ToStupidForOpenEHR 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|attachment](upload://uU55HI2WPrYR5iIYZTSTMZR5APP.json) (1.0 KB) Coded Entry is a reusable type I introduced... --- ## Post #17 by @ToStupidForOpenEHR 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|attachment](upload://4zeDgP0lcnP3ctOQt0ragKErLPA.json) (123.9 KB) --- ## Post #18 by @erik.sundvall [quote="ToStupidForOpenEHR, post:17, topic:2116"] [JSON EHR Server format.json|attachment](/uploads/short-url/4zeDgP0lcnP3ctOQt0ragKErLPA.json) (123.9 KB) [/quote] 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 https://specifications.openehr.org/releases/ITS-REST/latest/simplified_data_template.html#_json_formats 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](https://www.ehrscape.com/api-explorer.html) as shown in post 61 in https://discourse.openehr.org/t/separating-models-from-implementation/2093/61?u=erik.sundvall Also see post #12 in https://discourse.openehr.org/t/separating-models-from-implementation/2093/12?u=erik.sundvall --- ## Post #19 by @thomas.beale [quote="ToStupidForOpenEHR, post:14, topic:2116"] Fairly sure they, and me have spent enough time in software to decide that we think this is the best approach [/quote] 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. --- ## Post #20 by @ToStupidForOpenEHR 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.. --- ## Post #21 by @thomas.beale [quote="ToStupidForOpenEHR, post:20, topic:2116"] several specialised app’s working across fairly fixed domains [/quote] I'll just go out on a limb and say there are no fixed domains ;) I've never even seen a fixed single app data set. Everything changes, all the time... --- ## Post #22 by @erik.sundvall A post was merged into an existing topic: [Separating Models from Implementation](/t/separating-models-from-implementation/2093/84) --- ## Post #23 by @birger.haarbrandt [quote="borut.jures, post:10, topic:2116"] Many attempts were made to “simplify” OPTs and “protect” developers from learning openEHR AM/RM. None made them happy. [/quote] I'd like to disagree a bit here. I think FLAT and STRUCTURED formats + TDS + our own TDOs are covering different needs. For example, within HiGHmed, we use TDS/TDD for data integration with Intersystems Ensemble and Mapforce FLAT FORMAT has become quite handy for some app development and is used in multiple low-code tools like the ones provided by Better and Solid Clouds We were able to build a full AQL query editor using our DTO model (+ AQL parser) and some more applications which require some stronger focus on backend processing. Long story short: I don't think there can be one single perfect format that will make everybody happy to develop software. Having the openEHR RM and Templates allows to make flexible transformations and tweaks to serve different needs. Surely the openAPI approach would complement this by enabling some convenient support in multiple language. Hence, I think the situation has drastically improved since 2013 and an average developer is able to have their first "hello world" app up and running within 1-2 days. Not saying we cannot further improve but this is more about open educational resources and not the available tooling. --- ## Post #24 by @borut.jures You reaffirm my point - those that invested their time in learning the openEHR data model and architecture, have no problem using these simplified data formats. The formats are useful. Those that want to skip the learning part are usually not satisfied with any simplified data format. Even when the same format was successfully used by the developers from the first paragraph. --- ## Post #25 by @thomas.beale [quote="birger.haarbrandt, post:23, topic:2116"] I’d like to disagree a bit here. I think FLAT and STRUCTURED formats + TDS + our own TDOs are covering different needs. For example, within HiGHmed, we use TDS/TDD for data integration with Intersystems Ensemble and Mapforce FLAT FORMAT has become quite handy for some app development and is used in multiple low-code tools like the ones provided by Better and Solid Clouds [/quote] Summary: TDS/TDD is B2B-oriented; flat formats (and TDOs by the way) are C2B-oriented. I think [this diagram](https://specifications.openehr.org/releases/ITS-REST/latest/simplified_data_template/diagrams/simplified_template_definition.svg) from a few years a go is still not a bad way to think about the various kinds of mappings needed to get from canonical-based formats to OPT-specific messages (TDD-type things) and micro-APIs (TDOs). ![template-formats|485x500](upload://acmfjyUePGMTT3zO81zkMcIUrwb.png) [quote="birger.haarbrandt, post:23, topic:2116"] Surely the openAPI approach would complement this by enabling some convenient support in multiple language. [/quote] Indeed. [quote="birger.haarbrandt, post:23, topic:2116"] Hence, I think the situation has drastically improved since 2013 and an average developer is able to have their first “hello world” app up and running within 1-2 days. [/quote] Well I think we need a bit more tool chain in existence first, but that's the idea for sure. [quote="borut.jures, post:24, topic:2116"] Those that want to skip the learning part are usually not satisfied with any simplified data format. Even when the same format was successfully used by the developers from the first paragraph. [/quote] Yep. But they may not want to skip the learning; perhaps their employer never gives them time or space to go and get training on new methods. That is what is needed, as per my other post. --- ## Post #26 by @birger.haarbrandt The big advantage with FHIR is that people are experiencing success very early. Once you bought into it (because it is deceptively easy), you are going down the rabbit hole. There is just no simple solution for health IT, this is more about perception and psychology. --- ## Post #27 by @pablo @ToStupidForOpenEHR that is the canonical openEHR XML format for a COMPOSITION inside the VERSION object (a wrapper which adds versioning info to the clinical document), with a canonical JSON transformation applied (which is supported by the EHRServer to commit data, but is not a canonical JSON). That is why you see those @ attributes there, those are XML attributes in JSON notation. If you check the new openEHR Toolkit , it provides a tool to generate canonical JSON, which is the same data but slightly different, and openEHR valid, JSON format. --- **Canonical:** https://discourse.openehr.org/t/openapi-schemas-generated-from-bmm-files/2116 **Original content:** https://discourse.openehr.org/t/openapi-schemas-generated-from-bmm-files/2116