Hi,
Redoc and or elements (from stoplight) were on my radar. I tried also other alternatives, but these two looks better (Redoc reacher, elements nicer).
I will definitively contact you, but first we need to settle some goals/project from SEC-group perspective.
This is what I have created for the openEHR Toolkit to support the Definitions endpoints (since we store archetypes and templates)
openehr_toolkiit_definition_openapi2.json (8.3 KB)
The model schemas included are for the summaries of archetypes and templates, since templates are still in ADL we don’t have a schema for those (it would be a good idea to support AOM1.4 archetypes in JSON though).
Given the fact that in openEHR, the same set of APIs are used to manage all variations of templates and data instances, we may not be able to define a schema for apis dealing with individual artifacts (templates, compositions etc). We have to use examples to document this functionality.
I have converted a postman collection that we had made for testing EHRBase into OpenAPI. I can clean it up and share it for use as a starting point.
regards
can you please explain why?
I meant the request and response body schema, as these are different for each template. All the common elements like the headers, params can be defined.
What I would really like as a CDR feature is to generate endpoints for each template, where the schema (template) is ‘defined’ in OpenAPI. This would seriously lower the bar for new developers to start working with openEHR. Would make it even easier than FHIR I hope. @NeoEHR is quite far along this task, but he needs funding to got further.
Hi @joostholslag,
I think this is already achieved to some extend by STRUCTURED and FLAT formats.
Maybe I understand OpenAPI not well enough and this is a stupid question, but is there a reason why this cannot be defined based on WebTemplate and STRUCTURED format?
There is no such thing.
To explain the context: the effort here is to have a new ITS artefact. An openAPI based specification of REST API, which can be fed into document generators, but (more importantly from an ITS pov) also to code generators. This gives openEHR community access to contract-first approach to our REST API. As in, you can get the output of this work, generate both documentation and C#/Java/… code and use that to adopt your existing systems to openEHR, or implement one from scratch, fulfilling the contract of our REST API.
Now, the “clinical APIs” as we call them in Ocean (and others do the same elsewhere I guess), are focused on level 2 of two level modelling, and specifying them based on OpenAPI, to achieve the same benefits I explained above, is a different task. This was discussed in the SEC meeting and my comment was that it would make a good downstream work, once we have the initial output for REST API.
I cannot see any reason for not doing the auto-generation work based on STRUCTURED or FLAT or webtemplate etc formats for the clinical APIs, but then the formalism used to derive the auto generation would not have the ecosystem that OpenAPI has behind it. I’d see that as a downside, but there would be upsides as well, since every re-use of a generic tech comes with its loss of information, and doing what you’re suggesting may offer benefits over using OpenAPI for it. I’d say this scenario has some problems by nature though, which I outlined in my discussion with Erik here:
Hi,
I created a doodle page to find out the best moment to meet next week (preferably) with more people.
The link is here at Doodle. Anybody who would like to be involved (help) or are seriously interested in these specifications are welcome to join.
Please respond in the following few days so that we can pick the best date.
A one-off partial generation to help get the first version of an OpenAPI file could still be useful - even if then followed by manual only editing. Depends on how hard that is to build though 
This is possible at an implementation level documentation as templates are implementation specific.
openEHR REST specification does not cover template/composition definitions as they are implementation dependent. So we can define the general pattern in this spec and leave the implications to make it more specific for their documentation.
Regards
My question is rather the following: how would the payload of an HTTP request differ in openAPI compared to the structured format?
{
"klinische_frailty-skala": {
"category": [
{
"|code": "433",
"|terminology": "openehr",
"|value": "event"
}
],
"context": [
{
"status": [
{
"|code": "at0010",
"|value": "registriert",
"|terminology": "local"
}
],
"kategorie": [
"Lorem ipsum"
],
"start_time": [
"2022-02-03T04:05:06"
],
"setting": [
{
"|terminology": "openehr",
"|value": "home",
"|code": "225"
}
],
"_end_time": [
"2022-02-03T04:05:06"
],
"_health_care_facility": [
{
"|name": "DOE, John"
}
]
}
],
To my understanding, openAPI could provide a payload definition that could exactly look like the STRUCTURED format. It might not be the best approach (in our openEHR SDK, we have also a DTO model which looks different from STRUCTURED), but I’m wondering if I’m still missing the point. I can imagine there to be custom made APIs that suite different needs of developers, but I think these will be manually curated with some auto-generation to support the work.
The schema of an OPT is not different for each template. OPT is one specific format with one schema. I’m not sure I’m following.
Pablo, what I think Dileep refers is related to what Birger asks.
There are two ways of creating data discussed here:
The structure of the second way is derived from the underlying template, thus is different for each template - therefore we cannot publish a standard OpenAPI schema for the models - those have to be generated ad-hoc by tooling (sort of “Export as OpenAPI schema-yaml”, depending on the format used, STRUCTURED or FLAT).
So, to respond to Birger’s question, depending on the way you submit the data, you would need to have a different format, even though the content is semantically the same. Therefore the OpenAPI schema to validate such data should be different, or it should use ‘oneOf’ to validate both formats.
Our preference is to focus (for now) on the first way: the OpenAPI specification of the standard (canonical) COMPOSITION; later we’ll see about the other one - or hopefully tooling might want to address this issue.
Thanks @sebastian.iancu FLAT is not yet standardized and doesn’t have a schema AFAIK, I wouldn’t bother of even considering that format for the initial OpenAPI work. In fact I would go to JSON canonical only first. This “structured” neither exists, it’s just the canonical form named structured by some vendor.
If later other formats should be added, then I guess the schemas should be updated, but I would suggest to create a different definition file instead of putting different schemas inside the same definition. Of course if we can externalize the schemas it’s better, but for having “alternative” schemas, it’s better to have also separated definitions. In the long run it will get complicated to support alternative schemas under the same definition. It’s complex enough supporting two schemas for the canonical format in JSON and XML in the same OpenAPI definition.
Sorry again for being the dummy here, but what is the advantage of having a generic openAPI representation of canonical JSON? Will this allow to automatically derive a RM representation in any programming language with an openAPI generator? In this case: sounds useful for some cases but this is typically not a problem for us.
I thought this is mainly about taking templates and helping to derive an (open)API which can then be used to generate specific classes in any programming language to make openEHR client development much easier. Our SDK is limited to usage in Java and a generic approach to create classes which can be consumed by the API in Python, Ruby, C# etc. sounds like the killer feature.
So thanks for explaining, is this a fair summary?
Sure you are right, but if you would like to have those TDO/TDS then you’ll end up with template dependent schema. See also Seref’s post here.
noted! That was also my suggestion in latest SEC meeting.
perhaps we can still have a generic schema?! - to be discussed later…
The thing is that RM canonical is not always suitable to be a REST-API resource (think for instance on EHR vs EHRSummary, or the issue with some RM-invariants). And we cannot leave it open-choice to clients; we need to be a bit more strict and specifying it. On the way we could also choose to optimize some of REST resources (using composition, or derivation) over their RM counterpart, but that still has to be specified as OpenAPI schema. If all these are done, then implementers may use various tools to generate code in the language of their preference as you also suggested - and my hope is openEHR CDRs will use and extend this OpenAPI spec with their own additions (extra endpoints, headers, statuses, etc) in a very easy and consistent way, while also having their own rendering styling and branding.
That’s all valid and important enough to have, but I would say not right now - rather as a second stage. In my opinion it is more important (and doable) right now to have a better and computable specifications for our REST. In any case, these are all valid points (goals) to discuss in a meeting.
I think it is something that we must have specified - it is not really an optional aspect.
OpenAPI could work if you have one content-type for each payload schema for the same endpoint, for instance if we can identify canonical json, canonical xml, flat json, flat xml, etc. etc. canonical yaml??? with one content-type for each and one schema for each, that could work. But! this could generate a maintenance hell very quickly if not done correctly, we need to figure out how to work with multiple content types and schemas and what’s the best structure for the OpenAPI spec in this scenario, that is why I think we need to focus just on canonical JSON then add other formats, so we have one working spec and in the process we can learn how to deal with multiple formats and the maintenance issue.
Sorry I didn’t got that in the meeting.
I think an official flat format should have it’s own specific schema, though I’m not sure what a “generic” schema is, is that an schema with some elements defined and other elements open?
Canonical JSON is kind of the de facto format for the REST API spec. I don’t think it’s about code generation or anything, it just about supporting the default format in the OpenAPI spec then add other formats. Right now only canonical JSON and canonical XML have formal schemas in openEHR (part of the spec). Other formats are not yet part of the spec, so IMO we should put effort on have a complete OpenAPI spec with what are current official formats for openEHR, not community/vendor ad-hoc formats. Though, when those are formalized and part of the spec, they should have their own OpenAPI spec schema too.
I don’t think that is the focus of this task. Having an OpenAPI spec allows to generate/update documentation on the fly and that doc to be executable on top of an implementation to facilitate testing APIs. There are no templates involved in that, it just makes the maintenance of the REST API spec easier/faster. That’s kind of a first goal. Then, from that spec, it is possible to generate code as a byproduct, some might see value on that, though it is neither the main goal IMO. Another byproduct would be to generate test cases from existing metadata/data, like templates, and use that for conformance testing, and that might be related with what you mentioned, and would be of my special interest, but it’s not the main goal either, just something we might be able to do if we can release an official OpenAPI spec.
@sebastian.iancu when I mention canonical JSON, though I’m referring to the current RM schemas, in the context of the REST API those canonical JSON schemas should be the relaxed ones not the RM schemas. The relaxed ones should be derived from classes denoted in the Service Model specification, as the serialized form of instances of those classes.
Exactly, JSON is kind of the current de facto format for the REST spec, not an optional thing.
In the meanwhile - as status update, we are getting closer to Release 1.0.3 of our specification, based on OpenAPI.
The current state can be seen at: APIs Overview openEHR specs.
Feedback is appreciated!