Stream: committers
Topic: Proposal to remove ElementDefinition.example
Grahame Grieve (Oct 24 2016 at 20:01):
Discussion about GF#12057 led to FHIR-I proposing to remove ElementDefinition.example[x] on the grounds that it is a not very useful element, and must useful provision of examples is in full resource examples.
Grahame Grieve (Oct 24 2016 at 20:03):
in the content available to me, we have used ElementDefinition.example 24 times - in Identifier, Address, HumanName, and ImagingStudy, and 38 times in the Argonaut Provider Directory profile. In those cases, it seems to us that removing this element would not be a noticeable loss for implementers
Grahame Grieve (Oct 24 2016 at 20:11):
IG authors, if any of you believe that it's a mistake to remove ElementDefinition.example, please say so. @Keith Boone @Brett Marquard @Michel Rutten @Rick Geimer @Sean McIlvenna @Reuben Daniels @Stephen Royce @Eric Haas
Grahame Grieve (Oct 24 2016 at 20:23):
@Alexander Henket please think about this too
Alexander Henket (Oct 24 2016 at 20:26):
The Template ITS allows for multiple examples with a caption that explains what it is, and a type (valid | error | neutral) at every level because it is just not useful, possible or feasible to create full examples for every permutation of elements.
Especially for the most complex things it is has proven to be extremely useful to have those targeted examples.
Removing it in FHIR is a very bad idea.
Grahame Grieve (Oct 24 2016 at 20:27):
examples that are in error are a problem because they have to be valid
Alexander Henket (Oct 24 2016 at 20:28):
That may be so but in some cases you want to outline how *not* to do something. Granted this is not a majority of use cases, but I'm sure it is easy to skip validation of examples marked as known to be invalid
Stephen Royce (Oct 24 2016 at 23:01):
We haven't got into it much yet, but we were looking at using ElementDefinition.example; however, we would really like more than one example. What's the alternative?
Stephen Royce (Oct 24 2016 at 23:51):
Also, nearly every element definition we have in our current (non-FHIR) system (~1500) has examples. We have already had an internal discussion at which it was decided that these are still useful. However, as @Alexander Henket also mentions, we have multiple examples for each element definition, so an element containing a single value is not a lot of use. We also often have additional explanatory text associated with single or multiple examples.
Stephen Royce (Oct 24 2016 at 23:52):
Also, to be honest, when reading the FHIR documentation and trying to understand what is the scope of a given element, a few examples at the element level would not go astray.
Lloyd McKenzie (Oct 25 2016 at 01:16):
The belief was that a single example was insufficient. And if we allow multiple examples, then there'd be a question of whether the repetitions functioned as a group (e.g. multiple lines of DosageInstruction) or if they represented alternative usages. And if the latter, then you might want to label or comment on them. Or maybe stitch example values from different sequences together to generate a full example instance. Or. Or. Or. In short, the existing structure wasn't sufficient to be terribly useful. But making it complex enough to be useful could be complex indeed. So the notion instead was to punt the whole space into extensions and see what people come up with and whether the community evolves to any consistent behavior that would be appropriate to integrate into the core specification.
Stephen Royce (Oct 25 2016 at 01:36):
Well, I'm sure there's plenty of paralysis by analysis to be had here. For us, in logical models, we do not need to be able to generate a full example instance, &c. because the examples exist to aid human understanding of the concept and not to provide any machine level computability and so our requirements are fairly simple:
- Multiple examples are always alternatives; if an example functions as a group, then the entire group must be contained with a single example entry.
- We need to be able to comment on individual examples and the suite of examples on the whole (although the former is rare).
- As already stated, the examples do not need to be computable and, in particular, do not need to conform to the formal definition of the element being described; for example, if the element is a CodeConcept, simple free text examples are perfectly valid.
I understand the desire to allow the community to evolve their own behaviour in this space, but without direction, I suspect practice will fracture, not become consistent, especially given the small number of folks for whom this matters.
Lloyd McKenzie (Oct 25 2016 at 02:27):
@Stephen Royce If the number of people for whom it matters is a small set of those who care about ElementDefinition, then extension is where it should go. (And for the record, at the moment examples do need to be computable valid instances of the type - free text examples would go in DataElement.definition.)
Stephen Royce (Oct 25 2016 at 02:33):
If you follow that argument @Lloyd McKenzie, the whole ElementDefinition resource should be an extension! :wink:
Anyway, I do understand what you're saying, and I don't know how many folks do or don't care; I may be wrong about it being small; the point is that without direction, I don't think it's very likely that the community will develop consistent behaviour.
And yes, I realise that free text is fine as an instance of ElementDefinition.example; I was just being explicit about our requirements, that's all.
Lloyd McKenzie (Oct 25 2016 at 04:45):
The denominator is those who will implement the resource/data type.
Michel Rutten (Oct 25 2016 at 05:45):
From a tooling implementers perspective, the proposed change has little impact. I can see the motivation for removing this property, and I am fine supporting this if the community decides so.
Alexander Henket (Oct 25 2016 at 07:22):
I feel totally on the same page as @Stephen Royce with the exception that I do care whether or not examples go. I asked for 0..* and I get 0..0, you can imagine I'm not happy at all.
The fact that examples could be better by adding capability to annotate them and the ability to mark them explicitly as valid or invalid is not a good reason to say "let's skip them entirely because they can be better but we feel it is too complex to do so".
The grouping thing is a non-issue to me. Like Stephen said: every example is an individual example. Inline examples do not need validation, although if feasible it could be nice.
Extensions are necessary evil for non-conformance resources, but should be avoided if possible in conformance resources as there will be zero tooling to support them unless you write your own. For non-conformance resources you are expected to write your own (albeit while leveraging a reference framework)
I'm really totally not ok with removing the example 0..1 and stand by my request to promote to 0..*. For reference I've harvested on two ART-DECOR servers what projects currently have examples at Dataset (Logical model) or Template (profile) level:
*120 projects total
*45 have a total of 4071 inline dataset (Logical Model) examples and 1182 occurrences of multiple examples. 75 projects do not have examples in datasets
*65 have a total of 7745 inline template examples and 1773 occurrences of multiple examples. 55 projects do not have examples in templates
Alexander Henket (Oct 25 2016 at 09:07):
Example contents should be like "xs:any processContents="skip"" so there's no illusion that they are validated. To us an example looks like:
<example caption="Illustration of a Dutch BSN" type="valid">
<identifier>
<system value="http://fhir.nl/fhir/NamingSystem/bsn"/>
<value value="123456782"/>
</identifier>
</example>
or
<example caption="Do not use the OID for BSNs" type="error">
<identifier>
<system value="urn:oid:2.16.840.1.113883.2.4.6.3"/>
<value value="123456782"/>
</identifier>
</example>
Grahame Grieve (Oct 25 2016 at 09:09):
"xs:any processContents="skip"" - XML specific. We don't work with XML specific things
Alexander Henket (Oct 25 2016 at 09:10):
I'm sure JSON /Turtle has similar things. It was just to illustrate
Grahame Grieve (Oct 25 2016 at 09:15):
they don't have similar things at all
Alexander Henket (Oct 25 2016 at 09:16):
Isn't that what made JSON so appealing above XML governed by XSD? The ability to have arbitrary contents? Turtle I don't know that slightest thing of
Grahame Grieve (Oct 25 2016 at 09:18):
you can have arbitrary content, but there's no metadata signal for that, and we've not made any allowance for it in the FHIR metamodel
Alexander Henket (Oct 25 2016 at 09:20):
Ok, so apparently it needs to stay at a choice of every possible datatype. But that rules out structures to create examples of a grouping element.
E.g. an example of Observation.referenceRange
Grahame Grieve (Oct 25 2016 at 09:26):
yes that's not catered for, you're right
Alexander Henket (Oct 25 2016 at 09:32):
So is there anything that we can do about that limitation that lies within reason and assuming that inline examples stay in?
Grahame Grieve (Oct 25 2016 at 09:34):
not that one, really; that's a very fundamental thing in FHIR itself; only resources and data types are entry points.
Eric Haas (Oct 25 2016 at 18:49):
Nice to have for future use is really not that convincing for keeping it in. I've never used and always created example instances.
Lloyd McKenzie (Oct 25 2016 at 19:06):
@Alexander Henket The reason for dropping the element is that, as it, it's pretty useless. Allowing the element to repeat without more information would be ambiguous and still largely useless. Actually making it useful would mean significantly more complexity than is in the 80% for systems that are doing profiling. It's certainly possible to have standardized extensions. And if there's enough interest, these could be supported by the publishing tools and/or authoring tools like Forge. And maybe, eventually, there'll be sufficient use and consenus that introducing some sort of more sophisticated example structure would be useful. But at the moment, example is being used for different purposes by different people and in most cases isn't being used at all, which is a clear recipe for moving to the extension space.
Alexander Henket (Oct 25 2016 at 20:14):
"The reason for the proposal to drop the element" you mean I hope? Otherwise this discussion is a moot point and I'll be double disappointed
Alexander Henket (Oct 25 2016 at 20:21):
I'm sorry that my number of current usage and those of Stephen do not convince you. I have no more arguments to offer, and I do not get why the vast amount of in practice use cases spread over > 10 countries is just tossed aside. If you feel, like I do by the way, that example could be better if it had two more attributes (caption and type) and would repeat, then just do that.
The perceived added complexity is really in your mind. Examples are currently *not* validated and do not ask for them to be validated. There is no added complexity other than the assumption that the examples are rendered in the documentation.
There is *significantly* more complexity in creating full examples for every permutation of element variety.
Grahame Grieve (Oct 25 2016 at 20:24):
I'm.. confused... about the statement that examples are not validated. I can assure that all resources the fhir publishing tools touch are indeed validated
Alexander Henket (Oct 25 2016 at 20:26):
The ElementDefinition.example isn't other than what the datatype does by default. Or at least that was my assumption. If you already validate the inline examples, even better. Just make it a repeating validation and we're golden
Grahame Grieve (Oct 25 2016 at 20:28):
I validate the examples in the html narrative
Grahame Grieve (Oct 25 2016 at 20:28):
repeating validation?
Alexander Henket (Oct 25 2016 at 20:29):
for $example in $ElementDefinition.example
return validate($example)
:-)
Alexander Henket (Oct 25 2016 at 20:29):
Instead of just validate($ElementDefinition.example)
Alexander Henket (Oct 25 2016 at 20:31):
Validating an array of ElementDefinition.example and adding them all to the HTML output is my assumption of how much effort my request to go from 0..1 to 0..* is. Please help me understand why Lloyd thinks it is more than that?
Grahame Grieve (Oct 25 2016 at 20:32):
you're responsible for that, with the idea that you need descriptions, validity status, capability for invalid
Grahame Grieve (Oct 25 2016 at 20:35):
oh- and me too, since I'm using multiple examples, but I have them indexed and need a tag on them for offset, so that the examples are related to each other
Grahame Grieve (Oct 25 2016 at 20:35):
I'm presently doing that in extensions
Grahame Grieve (Oct 25 2016 at 20:37):
we could make examples a 0..* element that had a label and a value[x]. that would be a minimal change that I'd make use of (drop my extensions) and you would too. We night want to keep away from anything beyond that if the rest of FHIR-I are going to buy into it
Alexander Henket (Oct 25 2016 at 20:40):
Well the ticket just asked for 0..*. Nothing more, nothing less. The caption/type thing was a side note I probably should have omitted.
I'm very happy with 0..* examples that would need to be valid, and a label is heaven
Alexander Henket (Oct 25 2016 at 20:41):
To create an example that is explicitly invalid I can live with an extension.
Grahame Grieve (Oct 25 2016 at 20:41):
there's a technical issue there - there's a rule that no element with a choice of types can repeat
Grahame Grieve (Oct 25 2016 at 20:41):
hence the label
Grahame Grieve (Oct 25 2016 at 20:42):
but you can't have an extensions for an invalid example - they're validated too. All you could do is a string that contains some invalid resprensentation
Alexander Henket (Oct 25 2016 at 20:42):
Well the label also helps explaining why you have example X and Y
Alexander Henket (Oct 25 2016 at 20:43):
I think the question is "how invalid is the example"? I could not violate the base spec, but I could very likely create an example of CodeableConcept with a different codeSystem than the profile says I should use?
Grahame Grieve (Oct 25 2016 at 20:47):
bindings do not apply to examples.
Grahame Grieve (Oct 25 2016 at 20:47):
at least not to ELementDefinition.example
Alexander Henket (Oct 25 2016 at 20:48):
Ok, so the example is then only validated against the base spec which means I could also create purposely invalid examples so long as I do not violate the base spec?
Grahame Grieve (Oct 25 2016 at 20:48):
yes
Alexander Henket (Oct 25 2016 at 20:48):
The label would explain that the example is in fact not valid then. I'm all for it. Where can I sign?
Grahame Grieve (Oct 25 2016 at 20:49):
though I suppose I could change that and validate examples against the binding
Alexander Henket (Oct 25 2016 at 20:49):
When you start doing that you might find a lot of new errors. Even currently, I guess
Grahame Grieve (Oct 25 2016 at 20:50):
but you don't want me to do that
Alexander Henket (Oct 25 2016 at 20:51):
That's usually the case for any new consistency check.
but you don't want me to do that
Well I would like to know beforehand to decide whether or not I should implement invalid examples that way.
Alexander Henket (Oct 25 2016 at 20:52):
As long as doing profile validation of inline examples is not going to be on your todo-list, then I might consider doing it this way. Otherwise I'd probably be best off finding a different place
Alexander Henket (Oct 25 2016 at 20:53):
I care more about repeating labeled examples than I do about giving explicitly invalid examples.
Lloyd McKenzie (Oct 25 2016 at 21:10):
If we go to repeating, there are two use-cases - multiple repetitions = multiple distinct examples, each with a label; multiple repetitions = a single example showing multiple repetitions and how they work to gether (e.g. dosage instructions). If we're going to do this, we probably need a structure that supports both.
Grahame Grieve (Oct 25 2016 at 21:11):
carumba. you can string that together with labels, since it's for human consumption
Lloyd McKenzie (Oct 25 2016 at 21:12):
That'd be pretty ugly. You really want it all to render together.
Grahame Grieve (Oct 25 2016 at 21:13):
I reckon not; the labels would the text that string the pieces together.
Stephen Royce (Oct 26 2016 at 00:40):
I'm all for making examples 0..* and adding a label. That would cover nearly all our uses. 
Last updated: Apr 12 2022 at 19:14 UTC
