Stream: conformance
Topic: StructureDefinition.Description
Martijn Harthoorn (Jul 09 2018 at 13:16):
If you look what should go into the description of a conformance resource (take StructureDefinition for example), you see that most people leave it short (one line) or even empty. Take the core profiles or the StructureDefinitions of US-core. However reading the spec, it should contain quite a body of text:
"This description can be used to capture details such as why the structure definition was built, comments about misuse, instructions for clinical use and interpretation, literature references, examples from the paper world, etc. It is not a rendering of the structure definition as conveyed in the 'text' field of the resource itself. This item SHOULD be populated unless the information is available from context (e.g. the language of the profile is presumed to be the predominant language in the place the profile was created)."
John Moehrke (Jul 09 2018 at 13:48):
I think this is more an indicator of the maturity of the conformance resources, and the maturity of our use of them. Most of the human readable narrative is found in the IG narrative. Where there is an IG, this seems the logical place for it. One might even say that lengthy narrative in a StructureDefinition might lead the reader to the wrong understanding, as often the constraints are driven by the use-cases the IG is based upon.
Eric Haas (Jul 11 2018 at 20:49):
In the past I found markdown support in the tooling too limiting to support using SD.definition for everything and so used the IG to fully flesh out the description. I also agree with John that the SD.definition may not be appropriate for all use cases. But there are cases where I use it exclusively.
Michel Rutten (Jul 27 2018 at 13:31):
My colleague @Vadim Peretokin pointed out that on the official FHIR website, the introduction text on each resource page is taken from the ElementDefinition.definition property of the root element. He suggested to render the same text in Forge, to help users select an appropriate (core) resource or datatype, which make sense.
The official documentation of the StructureDefinition.description property (_"A free text natural language description of the structure definition from a consumer's perspective"_) suggests that this value is intended for rendering in selection UI etc. However for the core resource/datatype definitions, indeed the root element definition property seems to provide a better suitable, more informative description.
Forge could certainly also render root element definitions, in accordance with the spec itself. However, this makes me wonder whether we should try to improve/rewrite the current StructureDefinition.description property values of the core resources and datatypes, so the values are better suitable for the intended usage?
Last updated: Apr 12 2022 at 19:14 UTC
