FHIR Chat · Line noise in examples · IG creation

Stream: IG creation

Topic: Line noise in examples

Josh Mandel (Jan 06 2022 at 20:34):

We know from experience that developers grab and work with examples. The fact that FHIR includes lots of examples has helped with its rapid adoption. That said, as our publication tooling grows more sophisticated, examples are being forced to perform two jobs:

1. Show developers how the spec works (this is the raison d'être for examples)
2. Show the publisher tooling how to process each example (this is a side effect)

and (2) makes (1) harder, because our examples get annotated with a bunch of stuff that real-life instances wouldn't/shouldn't have.

To make this concrete: in ballot review I'm seeing this example:

{
  "resourceType" : "Observation",
  "id" : "prapare-multiselect-example",
  "meta" : {
    "extension" : [
      {
        "url" : "http://hl7.org/fhir/StructureDefinition/instance-name",
        "valueString" : "Prapare Multiselect Example"
      },
      {
        "url" : "http://hl7.org/fhir/StructureDefinition/instance-description",
        "valueMarkdown" : "This is a Prapare Multiselect Example for the *US Core Screening Response Observation Profile*."
      }
    ],
    "profile" : [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-observation-screening-response"
    ]
  },
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Resource \"prapare-multiselect-example\" </p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-us-core-observation-screening-response.html\">US Core Screening Response Observation Profile</a></p></div><p><b>status</b>: final</p><p><b>category</b>: SocialDeterminantsOfHealth <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://loinc.org/\">LOINC</a>#LG41762-2)</span>, Survey <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"http://terminology.hl7.org/3.0.0/CodeSystem-observation-category.html\">Observation Category Codes</a>#survey)</span></p><p><b>code</b>: Have you or any family members you live with been unable to get any of the following when it was really needed in past 1 year [PRAPARE] <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://loinc.org/\">LOINC</a>#93031-3)</span></p><p><b>subject</b>: <a href=\"Patient-example.html\">Patient/example</a> \" SHAW\"</p><p><b>effective</b>: 2021-11-12T17:59:15-08:00</p><p><b>performer</b>: <a href=\"Patient-example.html\">Patient/example</a> \" SHAW\"</p><p><b>derivedFrom</b>: <span>: PREPARE example</span></p><blockquote><p><b>component</b></p><p><b>code</b>: Have you or any family members you live with been unable to get any of the following when it was really needed in past 1 year [PRAPARE] <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://loinc.org/\">LOINC</a>#93031-3)</span></p><p><b>value</b>: Clothing <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://loinc.org/\">LOINC</a>#LA30126-9)</span></p></blockquote><blockquote><p><b>component</b></p><p><b>code</b>: Have you or any family members you live with been unable to get any of the following when it was really needed in past 1 year [PRAPARE] <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://loinc.org/\">LOINC</a>#93031-3)</span></p><p><b>value</b>: Child care <span style=\"background: LightGoldenRodYellow; margin: 4px; border: 1px solid khaki\"> (<a href=\"https://loinc.org/\">LOINC</a>#LA30127-7)</span></p></blockquote></div>"
  },
  "status" : "final",

... which of these fields are "real" and which are just helping the publisher do its job? (I think the extensions are all just hints to the publisher, and I think the profileis too -- but some of our IGs actually put conformance requirements around profile so you really need to know stuff to understand what it's safe to ignore).

Josh Mandel (Jan 06 2022 at 20:36):

I think it'd be good if we could avoid this confusion. Perhaps our published examples could strip out any "hints", or the hints could live elsewhere, or... probably other better ideas that y'all might have?

Grahame Grieve (Jan 06 2022 at 20:39):

I have no idea what those extensions are doing there

Grahame Grieve (Jan 06 2022 at 20:39):

and I don't think the profile should be there either

Josh Mandel (Jan 06 2022 at 20:49):

I had assumed publisher used profile as a hint to run validation checks... is that wishful thinking, or is there a different way to opt into that (like populating elements in the ImplementationGuide resource)?

Grahame Grieve (Jan 06 2022 at 20:51):

publisher does use profile to drive validation checks, but there are other ways to do that (yes, in the IG resource), so you should only do it that way if you're explicit intent is that the profile should be there in production examples

Lloyd McKenzie (Jan 06 2022 at 21:22):

We have a few challenges:

• a bunch of people want to put the documentation about a resource (title, description, what to validate it against) in the resource and NOT in the IG. SUSHI folks in particular. I think that's where these two extensions are coming from
• the ImplementationGuide currently only supports a single profile assertion for a particular example, and sometimes more than one is needed

What might help is an extension that we could include on elements that say "please strip this before rendering/publishing". That extension might appear on:

• id (because there are times when examples shouldn't have ids, even though the publication process requires them to
• meta.profile
• the title & description extensions
• maybe other things?

Would that be doable @Grahame Grieve?

Eric Haas (Jan 06 2022 at 22:57):

Althgough I disagree with Josh's complaint - they do no harm in my opinion. so pop em off if you want but not by an extension but a parameter set to default stripping. Also EVEN IF the IG resource could do the same, the overhead is greatly reduced by keeping the metadata on the instance, and as an end result will lead to more examples not less.

Lloyd McKenzie (Jan 06 2022 at 22:59):

Anything in an example that isn't expected to be in a production instance is confusing for implementers and thus is definitely a problem. So we definitely need to find a way to strip it. But I accept that there are going to be people who want to maintain the metadata as part of their instances.

Eric Haas (Jan 07 2022 at 00:05):

Confusing for implementers who copy and paste and do not comprehend what they are doing. ( been there and done that many times :-))

John Moehrke (Jan 07 2022 at 13:03):

I support the point Josh is making. The reader should not need to comprehend extensions well enough to know when an extension is intended and when it is there as an artifact of the publication process.
I do recognize these are much easier to manage in the github source when they are inside the resource.
I liked the idea Lloyd has to have in your project the things you want stripped out. much like the ignoreWarnings.txt.

John Moehrke (Jan 07 2022 at 13:05):

I guess it could be another extension within the resource that indicates the things to be removed, but I suspect this will make the github editing harder... so, both. a ignroeWarnings like thing to remove most of the cruft, and an extension to remove additional things specific to this example instance (like remove the id).

Lloyd McKenzie (Jan 07 2022 at 15:43):

I think the title and description extensions should just always be removed. I think we'll need a special extension for profile because, even within a single IG or even a single instance, there'll be some that should be removed and some that should stay.

Last updated: Apr 12 2022 at 19:14 UTC