Stream: implementers
Topic: fhir-codegen for OAS
Karl M. Davis (Sep 01 2020 at 16:02):
@Gino Canessa Last time I asked about OAS support for FHIR in general, the consensus was that there were pretty large chunks of stuff that wouldn't convert well from profiles to OAS / JSON schemas. Has that improved?
I'm specifically curious about response elements: does the output OAS spec include field descriptions, etc. for the response bodies?
cc @John French @Dave Shekhar @John Zulim @Sarah Tully
Karl M. Davis (Sep 01 2020 at 16:03):
(I'm following up on this thread: https://chat.fhir.org/#narrow/stream/179166-implementers/topic/hapi-fhir)
Gino Canessa (Sep 01 2020 at 16:20):
Hi @Karl M. Davis . I haven't delved into profile support for OAS specifically yet. It's on my list for the project, but will almost certainly be after the connectathon.
That said, there are a significant number of challenges, which is why I'm building tooling to do this instead of focusing on static generation. By loading the specs (currently supporting DSTU2 through R5 preview) I have access to all the base definitions, types, and descriptions. By connecting to the server, I have a list of actual resources, search parameters, etc. that are supported. With a fair number of settings I can define the general characteristics of the OAS file (e.g., OAS version, which operations you want in the file, case of id's, etc.).
Even with all that, most tooling forbids things like circular references (which happens on extensions, for example), so I am playing with expanding various definitions to be inline instead of references. It still needs to cut at certain levels (e.g., go 'x' levels deep, then to object), but the approach feels promising. I'll note that it's still experimental right now, and I'm trying to get a feel for what people actually need.
If you look at the example here you can get a feel for the current state - it has model information (with descriptions) for all the schema, and even has descriptions for the search parameters. That particular example was generated as a read-only spec (read/search) with fhir+json MIME type, etc..
Gino Canessa (Sep 01 2020 at 16:22):
Overall, it's still WIP but I feel good about getting to a useful point.
Karl M. Davis (Sep 01 2020 at 17:15):
Mind if I restate that back to verify I understood?
Basically: it does support response field descriptions, etc. but does not do anything with cardinality or with profiles that are more constrained than the general FHIR spec. For our use cases (the CMS Blue Button 2 APIs and friends which mostly revolve around ExplanationOfBenefit resources, then, it'd list all of the standard EOB fields, but not our extensions, and wouldn't help users identify which of the (hundreds of) EOB fields they might actually see back. That about right?
(Not at all a complaint, to be clear: just want to ensure that I'm tracking. I think that what you already have is very impressive!)
Gino Canessa (Sep 01 2020 at 17:22):
It does not yet include anything from profiles, but that is coming up shortly on my list. Beyond that, if you have a particular use in mind, I'm happy to add it to the list, or at least go through it to see what's possible.
Grahame Grieve (Sep 01 2020 at 21:21):
what's OAS?
Gino Canessa (Sep 01 2020 at 21:32):
Open API Specification - used to be called Swagger files.
Grahame Grieve (Sep 01 2020 at 21:40):
oh right. thanks.
Grahame Grieve (Sep 01 2020 at 21:42):
so we need to talk about this. Currently, the publication tooling generates OAS documents for any capability statements it sees. They are relatively fully populated, except for the deep issues in json schema. For some reason I don't understand, everyone is ignoring these and complaining that nothing is producing them.
Which is causing alternative work like this, which is... well, I'm all in favour of people taking work on, but I don't see how it will integrate with the existing tool chains.
Grahame Grieve (Sep 01 2020 at 21:42):
nor do I see how it will help with the actual problem, which is in the json schema side of things
Josh Mandel (Sep 01 2020 at 21:51):
I think one of the challenges with baking generation into the publication process is that there's a bunch of decisions that need to be made when creating an OpenAPI specification file -- different trade-offs for different target environments. So having something configurable is pretty important.
Grahame Grieve (Sep 01 2020 at 21:52):
what are those?
Josh Mandel (Sep 01 2020 at 21:58):
@Gino Canessa can provide much better detail than I can -- but we have seen specific implementations with limits on total size of generated files, number of attributes allowed, subset of json schema supported, whether references to content types (vs directly embedded types) are supported, etc.
Grahame Grieve (Sep 01 2020 at 22:00):
this is for openapi tooling problems?
Josh Mandel (Sep 01 2020 at 22:01):
Let's call it tooling diversity ;-) But yes.
Josh Mandel (Sep 01 2020 at 22:02):
And frankly we in the fhir community are pretty familiar with this type of diversity; there are lots of ways to build a valid fhir server, for example. Not everyone supports all the fancy stuff.
Grahame Grieve (Sep 01 2020 at 22:04):
well, I expected that your answer would be that we need to support diversity in the security/deployment parts of the openapi document. I hadn't been thinking about tooling diversity.
Grahame Grieve (Sep 01 2020 at 22:04):
either way, the conclusion is that there's no single openapi document for a capability statement?
Josh Mandel (Sep 01 2020 at 22:09):
I mean, we can endeavor to write one that is maximally complete and correct. I'm not saying that isn't worthwhile. I'm just saying that there's more to do beyond that.
Gino Canessa (Sep 01 2020 at 22:09):
Sorry, was recording my track orientation. Most of my work has been to support different tooling that cannot consume the schema files directly. For example:
- one toolchain I've been working with requires ID's to start with a lower-case, another with upper-case
- security toolchains often don't need schema, but do need paths, search parameters, and MIME types
- some toolchains work better with restricted sets (e.g., only access to these 5 resources)
- etc.
Gino Canessa (Sep 01 2020 at 22:12):
Between that and all the different "random" requirements (e.g., one app requires every element have a description that starts with an upper-case letter and ends with a period), I couldn't see how to make one that would suit all needs.
Grahame Grieve (Sep 01 2020 at 22:14):
well, that's all rather discouraging. But... if Josh is right, and there can be a canonical one that is worth us publishing, have you looked at what we do publish?
Gino Canessa (Sep 01 2020 at 22:20):
I've looked at it, but not in depth (looks good from cursory though). I've only seen fhir.schema.json though, nothing specific to a server (e.g., including paths, search parameters, etc.)
Grahame Grieve (Sep 01 2020 at 22:21):
well, here's an example - always generated, but apparently the editors are extremely resistant to actually linking to it:
https://www.hl7.org/fhir/us/core/us-core-server.openapi.json
(at least US core does link to it)
Gino Canessa (Sep 01 2020 at 22:24):
Ah, I do remember that one now (Eric has linked to it before). One of the first cases I was solving required OAS 2.0 without any schema elements, so I looked at it but moved on
Gino Canessa (Sep 01 2020 at 22:24):
(it also required the file be < 1 MB, if you want a laugh)
Grahame Grieve (Sep 01 2020 at 22:26):
the bit that makes me nervous is setting up a parallel infrastructure that creates openapi documents without any reconciliation, so that we get incompatible interpretations of openapi documents
Gino Canessa (Sep 01 2020 at 22:29):
Fair - but I can't see how to reconcile direct conflicts to make it useful for tooling
Gino Canessa (Sep 01 2020 at 22:30):
I see this as an on-demand type service (eventually I'll get to building the UI) - give it a URL, check some boxes, and get a file that works for your needs.
Gino Canessa (Sep 01 2020 at 22:31):
I am happy to put in additional steps/validations if that's the concern, but I'm somewhat at a loss as to how.. even converting between OAS 2.0 and 3.0 is rough in practice.
Grahame Grieve (Sep 01 2020 at 22:32):
I think I decided to only support 3.0.
Grahame Grieve (Sep 01 2020 at 22:33):
other than that... I'm not sure either. I don't suppose you can generate by starting with the one I generate and changing it? (probably not, but I don't understand how some of the issues you talked about can even describe the same API)
Gino Canessa (Sep 01 2020 at 22:35):
I probably could - but the codegen project works off the JSON specs directly today. The project builds the generated content for the fhir-net-api now, so something that major would need to be a different project altogether
Gino Canessa (Sep 01 2020 at 22:38):
How about for a next step I figure out settings that match to generate a document the same as the fhir.schema.json file, then add a comparison to the official one to my tests. That way, we know it can look the same.
Grahame Grieve (Sep 01 2020 at 22:44):
that sounds like a good idea
Karl M. Davis (Sep 02 2020 at 02:18):
Grahame Grieve said:
Currently, the publication tooling generates OAS documents for any capability statements it sees. They are relatively fully populated, except for the deep issues in json schema. For some reason I don't understand, everyone is ignoring these and complaining that nothing is producing them.
Same question for you, then, Graham: Last time I asked about OAS support for FHIR in general, the consensus was that there were pretty large chunks of stuff that wouldn't convert well from profiles to OAS / JSON schemas. Has that improved?
I'm specifically curious about response elements: does the output OAS spec include field descriptions, etc. for the response bodies?
Karl M. Davis (Sep 02 2020 at 02:24):
(Apologies: I'm actually not all that familiar with OAS myself (just hopeful that we'll get to leverage it!), and can't quite tell from the USCore example you posted above.)
Grahame Grieve (Sep 02 2020 at 04:27):
I generate an openapi document hooked up to the json schema - for the base FHIR resources. I think it's correct. But the tools are all over the place, and don't agree much
Last updated: Apr 12 2022 at 19:14 UTC
