FHIR Chat · Swagger generation - design choice · ibm

Stream: ibm

Topic: Swagger generation - design choice

view this post on Zulip Bruno R Neves (Dec 18 2019 at 00:04):

Will someone please explain the rationale for using inline schema for enumerations rather than a reusable type?

view this post on Zulip Lee Surprenant (Dec 18 2019 at 03:15):

We generate the inline enums for all Code elements with a Required binding to a particular ValueSet.
While some required ValueSets, like gender, happen to be used from a number of different resources, there are plenty of required code bindings that are only used in one or two spots.

I don't think moving the enums to a re-usable type would make it much smaller, but feel free to play with it / propose a change.

view this post on Zulip Lee Surprenant (Dec 18 2019 at 03:30):

In general, my goal for the IBM FHIR SwaggerGenerator was to emit a simplified FHIR schema that would make it easier for Swagger tools like IBM API Connect to ingest the definitions and display meaningful documentation and examples.
For example:

  1. FHIR supports extensions on primitive data types. However, the JSON serialization for that is a bit "interesting", and these primitive extensions aren't used much in practice...so the generated swagger omits those.
  2. FHIR supports "contained" resources, and so each resource type could technically contain any other resource type within it. However, that blows the schema out so that every endpoint would need to include every datatype. Instead, we include just the elements for the resource(s) being generated.
  3. FHIR choice elements with a type of * (like Extension.value[x]) can technically reference any FHIR data type, including rare/obscure ones like those defined at https://www.hl7.org/fhir/metadatatypes.html. For simplicity, we omit these from the swagger definition unless the Resource has an explicit field with this type.

In all three cases, the IBM FHIR Server is fully capable of handling these, but the FHIR Model just doesn't lend itself real well to Swagger (or even JsonSchema) and so we've tried simplifying it to make it work better.
We don't have a ton of experience with these simplified definitions yet, so your feedback on this approach is definitely appreciated.

Last updated: Apr 12 2022 at 19:14 UTC


An HL7 Website -