Stream: IG creation
Topic: Profiles in examples
Lloyd McKenzie (Sep 09 2019 at 20:55):
In GF#23965, I ask about allowing implementation guides to link examples to multiple profiles and provide a few situations where this can occur. On the FHIR-I call today, we realized there are three different things we need to be able to accomplish:
1. Identify that a particular profile/questionnaire/value set/other artifact is shown "in use" in a particular example (either the whole example or part of it). If a part, it might be nice to be able to link to the specific place(s) in the example where the use is shown.
2. We need to be able to indicate that an example as a whole or particular parts of the example are expected to be valid against a particular profile or graph definition
3. We don't want to embed meta.profile declarations inside our instance examples in order to trigger #1 or #2 if there isn't an expectation that instance authors must populate (and instance receivers can count on the population of) the profile - because generally they can't.
Lloyd McKenzie (Sep 09 2019 at 20:55):
We'd like thoughts from the IG community on the best way to meet these (potentially conflicting) objectives.
Eric Haas (Sep 09 2019 at 22:25):
I understood #3 the rest meant nothing to me. Can you clarify with possibly a straw man illustration or three
Lloyd McKenzie (Sep 10 2019 at 15:13):
1. Example: The same example instance might contain content that's valid against multiple SDC profiles (either because it's a single Questionnaire instance that happens to comply with the population, extraction and rendering profiles; or perhaps it has 'contained' value sets that comply with the value set profile or maybe it's a Bundle that contains a Questionnaire and a bunch of value sets and code systems which each comply with different profiles. Each of those 'profiles' should be able to point to that example instance as "an example of this profile". That means that the same instance might be an "example of" multiple profiles
Lloyd McKenzie (Sep 10 2019 at 15:16):
2. Because SDC doesn't say you need to declare profiles in your instances, we don't really want the example instance above to declare meta.profile. However, we do want to tell the validator that "within this Bundle, Questionnaire id 123 must be valid against the population, extraction and rendering profiles and value set #abc must be valid against the value set profile. Right now, the publisher presumes that if you declare a profile, then the root instance has to be valid against that profile - it doesn't allow for the profile applying to a Bundle entry or a contained resource.
Michel Rutten (Sep 10 2019 at 15:17):
We could add an (extension) element to ElementDefinition.example that allows to specify a reference to an external example instance (instead of inlining examples in the profile). Multiple profiles could then point to a common example instance. However it's probably better to capture this in the IG resource instead of the StructDef, for better separation & reuse.
Eric Haas (Sep 10 2019 at 16:54):
for 1, why not add the profile to meta? that is how it is prescribed in spec. why even have it if we don't use especially for examples. That is how I validate against the profiles. @Michel Rutten if we have meta.profile why add this extension. I don't see the cost /benefit here?
Eric Haas (Sep 10 2019 at 16:56):
for 2 see my response above, I don't understand why the example ( exemplars really) should not have the profile declared. and yes I am being pedantic here instead of you for a change....
they are illustrative of how to do it and are presumed to be conformant so how else would you do that without the meta profile.
Again if we don't want to use meta profile - why do we even specify it in the first place?
Eric Haas (Sep 10 2019 at 16:58):
for 2 im still unclear what the issue really is, is that the validator is not smart enough? or it is not possible technically to do this if each artifact in a bundle or contained artifacts has a meta profile.
Eric Haas (Sep 10 2019 at 16:59):
again I ask the fundamental question of what good is meta profile if we don't use it in these situations.
Lloyd McKenzie (Sep 10 2019 at 17:44):
We don't want it in meta because that then makes implementers think that they need to put the profile in the instance - and other imiplementers think that they can expect to see the profile in the instance. Neither are true.
Eric Haas (Sep 10 2019 at 17:54):
I fail to see how you can indicate what profile an instance adheres to without putting that information in the instance. ... and you seem to be saying that even if you can tell implementers why we are using meta.profile for these examples it is too toxic to use.
Eric Haas (Sep 10 2019 at 17:54):
I am confused
Lloyd McKenzie (Sep 10 2019 at 18:18):
It's not toxic - it's just not required or something implementers can count on. We need to be cautious about putting that stuff in examples - and especially cautious about putting it in all examples, which would certainly set the wrong expectation.
Mark Kramer (Sep 10 2019 at 18:21):
Maybe this just shows how dumb I am, but I think populating meta.profile is perfectly fine and I would go so far as requiring the inclusion of the profile name in meta.profile. If someone sent an instance to an mCODE endpoint and that didn't declare the profile, I would not accept it.
Lloyd McKenzie (Sep 10 2019 at 18:22):
This issue is raised because the IG allows indicating profiles associated with an instance, but only to a limited extent. If we improve the ImplementationGuide, we may be able to strip the information out of the examples. (From a maintenance perspective, it may well be that we include the profile declarations in the instance and move it into the IG definition as part of publication.)
Lloyd McKenzie (Sep 10 2019 at 18:24):
@Mark Kramer There will be tens of thousands of profiles. Instances will be sent to machines that care about profiles the author has no knowledge of. Therefore, receivers can't count on profiles being declared unless they're operating in a closed environment. Profiles never change the meaning of an instance and are always ignorable, so forcing them to be sent is not appropriate.
Eric Haas (Sep 10 2019 at 18:49):
so again if nobody is going to use meta.profile then why did we define it in the first place. I contend it is appropriate to use in the IG example, but now I see you want to make a magic IG wide assertion on conformance to profiles - but that seems like a lot of work if we already have a way and it ( magic IG wide way ) not going to work that way in the real world so we are back to your original concern about misleading the reader.
Grahame Grieve (Sep 10 2019 at 19:23):
There are times when it is appropriate to use meta.profile, and that’s why we defined it. But there’s lots of times when it isn’t, and this is important - there’s a tension between being explicit about profiles and allowing for wide reuse. for instance, in argonaut, we didn’t make the profiles explicit, which is great, because a set of entirely different resources built to rules that have entirely different history (say, interopen) can also happen to be valid. But if both interopen and argonaut had or do specify meta.profile, then you can no longer satisfy both sets of requirements, even though they are fundamentally compatible
Grahame Grieve (Sep 10 2019 at 19:23):
So we don’t want the community to start using meta.profile everywhere simply because the IG authors needed to do that to get the validator to work. We want them to use it carefully where the benefits justifies the cost.
Grahame Grieve (Sep 10 2019 at 19:24):
That is, the cost to implementers. hence why I want the IG authors need to be met some other way
Eric Haas (Sep 10 2019 at 21:07):
IG authors need to be met some other way
I had assumed currently within an IG you need the meta profiles for the ig validation to work for that profile. Is that true?
so here are 2 suggestions:
If the Ig validator just validates for all the profiles of a type then if you only have a single profile for a type then just validate on the default profile, if you have multiple types then add an extension to the IG resource for that instance to define the profile(s) to validate against.
or
Add a boilerplate on each example pages explaining (unless we think nobody will ever read it ) :
- why there is a meta profile
- and that is not appropriate in all use cases,
- think about for your use case
- and there are other ways to specify a profile when you validate too...
Grahame Grieve (Sep 10 2019 at 22:14):
I had assumed currently within an IG you need the meta profiles for the ig validation to work for that profile
yes, that's true. But I want to change that so that we don't imply you need to do that in production in order to make publication work right
Grahame Grieve (Sep 10 2019 at 22:15):
yes. or a 3rd suggestion which is that we already have reason to beef up the example arrangements in an IG, so handle this issue there too
Lloyd McKenzie (Sep 10 2019 at 22:50):
Validating against all profiles will throw a ton of spurious errors and will also slow down the build. Disclaimers are verbose, annoying and commonly ignored. I'd prefer something in the IG.
Eric Haas (Sep 11 2019 at 00:05):
Validating against all profiles will throw a ton of spurious errors and will also slow down the build
I am not suggesting this rather:
- validate by type
- ability to define which profile to validate in the ig resource.
- default would be to validate against all profiles of type = which punishes those who don't define it in the ig.resource
Eric Haas (Sep 11 2019 at 00:05):
I think this what Michel intimated to earlier
Lloyd McKenzie (Sep 11 2019 at 00:06):
Validating by type doesn't help when there are commonly multiple profiles per type - and some instances that aren't expected to be valid against any profiles.
Lloyd McKenzie (Sep 11 2019 at 00:07):
My point is to allow defining it properly in the ig.resource. If someone does use the IG resource, you wouldn't want those with no specified profile to be validated against an arbitrary default profile
Eric Haas (Sep 11 2019 at 00:07):
have reason to beef up the example arrangements in an IG
what does this mean exactly?
Eric Haas (Sep 11 2019 at 00:10):
My point is to allow defining it properly in the ig.resource. If someone does use the IG resource, you wouldn't want those with no specified profile to be validated against an arbitrary default profile
why would you not validate against a profile in the IG if you define a profile for type?
anyway we are arguing over default behavior - I think the lazier approach is to assume by all profiles of type and explicity state otherwise - you think it is the opposite way
Grahame Grieve (Sep 11 2019 at 04:44):
Observation.... no reason to validate every observation against every observation profile.... author will be buried in errors
Eric Haas (Sep 11 2019 at 04:52):
I'm worried about authors too and keeping the bookkeeping to a minimum by only only declaring the profiles that need to be explicitly profiled or none. I'm assuming the only profile that the validators cares about are the inherited ones and the ones in the IG and most cases ( not lloyd ;-)) you only have a few profiles in your ig and all your examples are going to conform to those.
Eric Haas (Sep 11 2019 at 04:53):
I'm concerned about the overhead as an author but not sympathetic to errors on examples.
Oliver Egger (Sep 11 2019 at 08:01):
Coming late to this topic, I would favor an approach like 3 where I can specify for each profile which resource (or part of) is an example and the igpublisher would validate that example according to the profile, so instead of putting meta profile in the example and specify the exampleCanonical Url in the ImplementationGuide, directly referring in the example having an examples (0..*) entry in the ImplementationGuide for each profile. On my wish list would be supporting examples for logical models, like CDA documents which could then directly be validated with the logical model and igpublisher, but then the igpublisher would need to be extended to handle non fhir resource content (no type/id guaranteed).
Lloyd McKenzie (Sep 11 2019 at 12:46):
What I lean toward is:
- when authoring, you embed profile declarations in your instance because that's the natural (and least error-prone) place to do it.
- we have an extension that lets you flag profile declarations as "to be retained" (on the grounds that that's less common - and we want people to have to do extra work if that's what's needed)
- remaining extensions get trimmed by the publisher process and the IG for each resource includes a list of paths based on id (e.g. Bundle.entry.resource.where(id='foo').contained(.where(id='bar') and for each path identifies what profile(s) should be enforced by the validator for that node.
Lloyd McKenzie (Sep 11 2019 at 12:47):
The links in the IG would also be used to create cross-maps so that profiles could list their associated examples (including maybe hyperlinking to the correct Bundle.entry) and examples could include references to their "demonstrates profile(s)"
Eric Haas (Sep 11 2019 at 14:06):
@Lloyd McKenzie that is making my head spin. but I see a method to your madness. So the IG resources could slurp this up from the instance right?
Eric Haas (Sep 11 2019 at 14:07):
but then you may get caught using source instances instead of published instances is the only downside
Lloyd McKenzie (Sep 11 2019 at 14:12):
Shouldn't be any issue with that as the publisher controls what shows up in the published side. Only real issue would be if someone uses a different template that doesn't do the same processing.
Grahame Grieve (Sep 11 2019 at 14:12):
that wouldn't be done in the template
Lloyd McKenzie (Sep 11 2019 at 14:13):
Stripping stuff out would be template driven. Extracting it into the IG would be done by the publisher
Richard Townley-O'Neill (Sep 12 2019 at 02:54):
- we have an extension that lets you flag profile declarations as "to be retained" (on the grounds that that's less common - and we want people to have to do extra work if that's what's needed)
I already add profile declarations to examples when creating IGs (to test the examples and the profiles) and delete most of the declarations when finalising the IG (to avoid misleading readers who pay more attention to examples than the profile into thinking that profile declarations are wanted or preferred).
I like reversing Lloyd's proposal: having an extension which means "to be deleted when generating the ig".
- The default behaviour will be the behavious expected by the naieve
- Existing IGs will behave the same when built
- If anyone can think of a use, this could be used in any part of an example to suppress publication of content.
Lloyd McKenzie (Sep 12 2019 at 03:03):
The problem is that the naive will not bother to set the extension - which will mean their examples will contain profiles when they shouldn't (and they won't notice or care). Requiring the use of the profile, on the other hand, will mean that the naive will find their profile declarations are vanishing (and potentially causing validation issues) and will complain - and then get pointed to the extension after having been grilled on why they're mandating profiles in the instances.
Lloyd McKenzie (Sep 12 2019 at 03:04):
I.e. Forcing the extension for the less-desired behavior will increase the incidences of the desired behavior.
Richard Townley-O'Neill (Sep 12 2019 at 04:45):
Does the validator test the examples before or after the profile declarations are removed?
If it tests after, naieve users will think that their examples pass validation when they are untested.
I guess it will have to test them before trimming out the profile assertions.
Lloyd McKenzie (Sep 12 2019 at 11:15):
The validator would test the instances after the declarations were removed, but would have the IG passed in as an argument, which would tell the validator to test the relevant locations against those profiles anyhow.
Lloyd McKenzie (Sep 12 2019 at 11:16):
The whole point is to ensure the validator checks what it should, while not mandating that the profiles be in the instances.
Last updated: Apr 12 2022 at 19:14 UTC
