Stream: terminology
Topic: Unapproved breaking change
Grahame Grieve (Aug 13 2018 at 13:13):
Lloyd has just pointed out to me (though he didn't realise the implications) that I made an unapproved breaking change to the value set resource. in my defense... it was late and I was tired....
Grahame Grieve (Aug 13 2018 at 13:13):
you can see the change here: http://services.w3.org/htmldiff?doc1=http%3A%2F%2Fhl7.org%2Ffhir%2F2018May%2Fcodesystem-filter-operator.html&doc2=http%3A%2F%2Fbuild.fhir.org%2Fcodesystem-filter-operator.html
Grahame Grieve (Aug 13 2018 at 13:13):
I renamed the code descendent-of to descendant-of
Grahame Grieve (Aug 13 2018 at 13:14):
this is a correct spelling fix, but the task under which I did that was an auto-approved typo fix, They don't apply to codes, only to narrative.
Grahame Grieve (Aug 13 2018 at 13:14):
my error to accept a general search and replace...
Grahame Grieve (Aug 13 2018 at 13:15):
Does vocab want to stay with the spelling corrected code, or revert to the original spelling?
Rob Hausam (Aug 13 2018 at 13:48):
I would vote for staying with the corrected spelling if we can.
Robert McClure (Aug 13 2018 at 14:33):
Also agree that this should be approved with the correct spelling. Any idea of the technical impact to implementers and do we need to mitigate in some way? Give notice?
Grahame Grieve (Aug 13 2018 at 19:01):
well, I need to note the change in the list of substantive changes
Rob Hausam (Aug 13 2018 at 20:09):
There are a few other places that "descendent" is showing up (and it is a legitimate word, but it's an adjective rather than a noun). I see it currently in fhirpath.md, codesystem/loinc.xml, v3/source.xml, v3/source_nl, v3/OID_Report.csv. It's also in a few places in release2 and release3, but that shouldn't matter. And it's also in spelling/english.dic. I'm assuming that likely it should be removed from the dictionary to be able to catch the misspelling, and "descendant" is already there. Happy to make a tracker and fix those if you want.
Grahame Grieve (Aug 13 2018 at 20:57):
we can't fix it in codesystem/loinc.xml, v3/source.xml, v3/source_nl, v3/OID_Report.csv
Grahame Grieve (Aug 13 2018 at 20:57):
or in release2 or release3
Grahame Grieve (Aug 13 2018 at 20:57):
good to fix in fhirpath.md
Michael Lawley (Aug 13 2018 at 21:41):
Technically it's not a mis-spelling, it's only a less common spelling according to the various dictionaries I've looked at (but possibly skewed sample as I started my search with -ent)
Rob Hausam (Aug 13 2018 at 23:23):
In what I saw the most common understanding seemed to be that 'descendent' is generally (but not absolutely) considered to be the adjective (i.e. "the descendent concepts") and quite a bit less commonly used, and 'descendant' is the noun (i.e. "the descendants of the concept"), which is almost certainly what we were intending. So you can kind of construe 'descendent ' to work, but being consistent with 'descendant' would seem to be best when we can do it.
Alexander Henket (Aug 14 2018 at 05:18):
Fixed spelling errors is among the things that made V3 so hard to work with. Your V3 wire format would change every release because of it, even if nothing else changed.
This fix will add another if/then/else to systems that want to stay compatible with R4 and as much as possible before that. It will become ever more important to have the FHIR version pointed out in the meta to at least 'see' which version of ValueSet you are dealing with. Unfortunately there is some tool lag there, and at least until about a month ago a number would trip over that because the version profile string would not resolve.
So in short: I'm not thrilled about breaking spelling fixes, especially if the thing that is fixed is not truly wrong or misleading, i.e. if the fix is for beautification.
Grahame Grieve (Aug 14 2018 at 07:21):
This would be the only breaking change to the value set wire format
Grahame Grieve (Aug 14 2018 at 07:21):
same for codeSystem.
Grahame Grieve (Aug 14 2018 at 07:22):
that's enough to make me want to undo the change, and live with the spelling mistake
Grahame Grieve (Aug 14 2018 at 07:23):
.. given that we can pretend it's not truly a spelling mistake ;-)
Alexander Henket (Aug 14 2018 at 07:25):
Somewhat related: is it possible to make the version strings in profile resolve? I think that would help tools that now trip over that. E.g.
http://hl7.org/fhir/3.0/StructureDefinition/ValueSet
Grahame Grieve (Aug 14 2018 at 11:50):
it's on my task list but it's not critical for getting to ballot
Grahame Grieve (Aug 14 2018 at 11:50):
it will happen though
Grahame Grieve (Aug 14 2018 at 21:34):
ok. so Rob H & Peter J voted for staying with the corrected spelling. I vote to go back to the wrong spelling, as does Alexander H. No other feedback - is there any chance we can close this out today?
If I don't get any feedback, I'll use Product Directory perogative and reverse it as an unapproved changed that is breaking, and to normative content
Lloyd McKenzie (Aug 14 2018 at 21:53):
I have a preference to fix it, but I'm not sure I count. The fact it creates a conversion issue from R3 to R4 isn't a huge reason for me given there are other breaking changes. Obviously if this was discovered later, we'd have had to live with it, but it was discovered in time and has already been fixed. Breaking it again seems inappropriate.
Elliot Silver (Aug 14 2018 at 21:59):
Although I don't really have a horse in this race, I'll second Lloyd's position. We've responded to other objections about breaking changes by pointing out that DSTU/STU means things can break, and no compatibility is promised. And, if you are migrating resources from STU 3 to R4, this is going to be one of the easiest breaking changes to code for. My opinion is that we should change, and now is the opportunity to do it.
(And maybe we should put an element name spell checker into the build to catch this earlier next time. :wink: )
Lloyd McKenzie (Aug 14 2018 at 22:00):
We have done spell-checking on element names. Doing on terminology is...painful
Elliot Silver (Aug 14 2018 at 22:01):
Ah, right. Ouch.
Michael Lawley (Aug 14 2018 at 22:06):
I've kind of been on the fence here...but it would be best for the spec to be consistent in its spelling and breaking changes are expected between STU3 and R4 (looking at our Ontoserver code there's about 6 lines that will need fixing and a dozen or so ValueSets, all of which are trivial), so if pushed I'd say make the fix
Alexander Henket (Aug 14 2018 at 22:59):
Lloyd mentions that are other breaking changes. Grahame mentioned this would be the only breaking change for ValueSet. I was also under the impression that ValueSet at FMM 5 would be more stable than other parts of STU3 > R4. The fact that we are going to R4 doesn't open up every resource equally for breaking changes, does it?
Sure it's tempting to fix a beautification issue, descendent-of is lesser common but legal English, but my day-to-day V3 work tells me that beautification is usually not worth a breaking change.
Rob Hausam (Aug 14 2018 at 23:53):
If you consider "descendent" to be an adjective (which seems to be the majority view), then "descendent of" wouldn't be legal English.
Robert McClure (Aug 15 2018 at 00:50):
Change it. But I too am not as affected as others
Grahame Grieve (Aug 15 2018 at 01:35):
The fact it creates a conversion issue from R3 to R4 isn't a huge reason for me given there are other breaking changes
no other breaking changes for valueset and code system. Most other substantive changes back apply to value set.. this would mean that we can't have a common value set editor for r3/r4.... I think that some of you that say 'I am not affected' haven't thought this through
Peter Jordan (Aug 15 2018 at 03:16):
@Grahame Grieve - I'd be happy if you made a Product-based call on this. That should override individual desires to fix a relatively minor grammatical error that probably wouldn't even make the top 500 modern offences against the English language.
Grahame Grieve (Aug 15 2018 at 03:23):
I think I'm going to. if nothing else, on procedural grounds, to save the ballot. I will launch the ballot with an explicit call for comments on breaking changes. And this will be the only breaking change on ValueSet (we have a couple on $expand). as such, existing implementers get to call on it; I would expect it will be negative... and so the ballot fails
Grahame Grieve (Aug 15 2018 at 03:26):
though the committee overrules either way in the end... but I'm not hearing a strong opinion either way from the participants here or the co-chairs. So ping just in case committee wants to take the issue up or just accept the my product directors decision:
@Ted Klein @Carol Macumber @Russ Hamm @Robert McClure @Rob Hausam @Heather Grain (+ @Joel Schneider @Reuben Daniels - incoming chairs I think it was)
Rob Hausam (Aug 15 2018 at 03:48):
I'm not sure I exactly followed what you said before - I think at first you said that you're going to make a product-based call on procedural grounds to save the ballot (which I presume means back out the change), and then you said at the end that "this will be the only breaking change on ValueSet ... I would expect it will be negative ... and so the ballot fails" (which sounds to me like you're leaving the change in and predicting what will happen). So if you can clarify which yoiu meant, that would be helpful. You're also asking the Vocab co-chairs (which I think is good). Joel and Reuben are nominees rather than incoming yet - but I agree that they should be included. I don't feel like I can say for sure which is the "right" choice. My bias is to try to fix things and make them right - but only when it's reasonable to do so, which is the hard part. I will say that if we're "afraid" (so to speak) to fix relatively small things like this even before we've actually gone normative, it makes the thought cross my mind that maybe we're pressing too hard to get to normative on this too fast. But I also know why we want to get there and that there's potentially a significant cost to not getting there soon enough. So I will be slightly disappointed if you back out the fix, and I expect that we may still want to change it in the future (which will be even more painful to decide), but I certainly can live with the decision either way.
Grahame Grieve (Aug 15 2018 at 03:50):
careless verb tense on my part:
this would be the only breaking change on ValueSet ... I would expect it will be negative ... and so the ballot fails
Rob Hausam (Aug 15 2018 at 03:52):
that makes it clearer - thanks
Grahame Grieve (Aug 15 2018 at 03:53):
I will summarise:
- we detected a breaking change introduced to a normative candidate that was made by an editor by mistake
- that editor happens to be me, but that shouldn't (nor has it, I think) made any difference to process, which is:
- consult the committee to see whether the committee has a strong opinion that the change should not be reversed and intend to authorise it retrospectively
- in the absence of strong endorsement of the change by committee, reverse the change
- the committee can appeal the process - though I think it's reasonable, or rule on the change itself
Lloyd McKenzie (Aug 15 2018 at 03:54):
Based on our compatibility rules, the only case where we could make this fix after normative is if we had strong evidence that it hadn't actually been implemented and correcting it wouldn't impact the community - which is definitely not the case here.
Grahame Grieve (Aug 15 2018 at 03:54):
oops. mssed a rather significant 'not' in there - edited to correct it
Grahame Grieve (Aug 15 2018 at 03:54):
yes that is clearly the case; don't fix now, never fix. There's no question about that
Lloyd McKenzie (Aug 15 2018 at 03:54):
If we don't fix it now, it will never be fixed. (And any equivalent changes we haven't detected yet will also never be fixed.)
Grahame Grieve (Aug 15 2018 at 03:54):
yes that too
Rob Hausam (Aug 15 2018 at 03:54):
what I really don't like the most the way it is currently is that we're inconsistent - in some places we have descendant, and in others it's descendent (even though we intend for them to mean the same thing) - I don't think that's a good situation
Grahame Grieve (Aug 15 2018 at 03:55):
but we'll never be able to do anything about that
Grahame Grieve (Aug 15 2018 at 03:55):
if I reverse the change, I'd note the spelling issue explicitly against the definition of the concept
Lloyd McKenzie (Aug 15 2018 at 03:56):
(and why it's being left, I presume?)
Grahame Grieve (Aug 15 2018 at 03:56):
y
Rob Hausam (Aug 15 2018 at 03:57):
it's obviously good to note it, but I think it still will tend to be confusing and somewhat difficult to remember which one to use where
Grahame Grieve (Aug 15 2018 at 03:58):
that's the grounds for changing it. yes. But if the committee wants to do that, it has to be very positive that making r3 value set not compatible with R4 value set is worth it. And I posit that we'll be carrying R3 profiling - and value sets- for a long time....
Grahame Grieve (Aug 15 2018 at 03:59):
and as product director, I care about the functionality of that area. We are not richly endowed with tools, and the IG editors will certainly support the notion that changing the conformance resources introduces a lot of pain.
Grahame Grieve (Aug 15 2018 at 04:00):
I don't feel that fixing this spelling mistake (which is a little equivocal) is a good investment on our part
Rob Hausam (Aug 15 2018 at 04:04):
again, to be clear now that I've thought about it a bit more, I care much more about the consistency in using the word than I do about which variation is actually the "correct" spelling
Grahame Grieve (Aug 15 2018 at 04:07):
so reverse all the uses associated with the concept, and add a note to the concept...
Rob Hausam (Aug 15 2018 at 04:11):
and I agree it's true that R3 will be around a long time, but I think we all expect that R4 and then R5 or whatever we might have will be around even longer
and we do have the inter-version converters and have invested considerable effort in making them robust - and I think we could use ConceptMap for this (as well as other logic that could be applied)
but I'm not really trying to advocate against your position, and I don't think I have much more to say on it
Rob Hausam (Aug 15 2018 at 04:20):
I will say one more thing, though - leaving inconsistencies like this in the spec (when we know they are there) to me makes us seem sloppy, at best (which isn't good)
Joel Schneider (Aug 15 2018 at 05:54):
It's an interesting dilemma. Not fixing it amounts to treating the R3 (mis)spelling as normative, but removing the descendent-of code makes filter-operator into a misbehaving code system for those who have implemented it under R3.
Is there any possibility a descendant-of code, synonymous with descendent-of, could be added to the R3 filter-operator code system? Is this intended to be a versioned or versionless code system?
It seems we haven't yet identified anyone directly impacted by removal of the descendent-of code defined in R3. Should that be a consideration?
Grahame Grieve (Aug 15 2018 at 06:20):
impacted: any tool that edits value sets or uses them (anyone in the IG publication business). value set authorities like VSAC, Art-Decor... Right now, they could have a single repository... but not with this change
Grahame Grieve (Aug 15 2018 at 06:20):
adding a synonym? interesting idea... but I'm not sure how that plays out
Reuben Daniels (Aug 15 2018 at 08:42):
Based on the discussion so far (and particular the points made by Rob H, Lloyd And Michael L), I lean towards making the fix now.
Carol Macumber (Aug 15 2018 at 11:30):
R3 was STU, breaking changes are part of the known risk in implementation. Yes, it was maturity level 5, but that doesn't preclude it from breaking changes until it goes normative (as far as I know). Though I am squeamish about the inconsistency of leaving other instances in the descendent-of state, not fixing this one because we can't fix the others doesn't seem right either. So, based on the discussion thus far, I vote to make the change now.
Alexander Henket (Aug 15 2018 at 19:12):
As for ART-DECOR: we don't store as FHIR ValueSet. We generate. In the generation process I can switch to using descendant-of. It's doable if the meta.profile versioning system works so ValueSets on GitHub for example where they live as files can have version markers. Without working version markers, tools will have a harder time figuring out what's what.
My fear is that we will have broken tooling for months to come over a spelling error in a code. Codes should not be treated as readable strings. That's what I like about OIDs and hold against URIs, and that's what I like about numeric/mnemonic codes and hold against readable codes. You should never have to discuss spelling errors in technical designators. Once issued they "are".
Peter Jordan (Aug 15 2018 at 21:09):
Good points from @Alexander Henket about codes as surrogate and immutable identifiers. As such one could argue that natural language spelling considerations simply don't apply to such identifiers.
Grahame Grieve (Aug 15 2018 at 21:09):
@Michael Lawley - would you release a second version of your value set editor for this change?
Grahame Grieve (Aug 15 2018 at 21:10):
@Peter Jordan that's why I should never have made the change. I regret doing so now. :disappointed:
Rob Hausam (Aug 15 2018 at 21:15):
well, maybe it's actually more appropriate to regret not using meaningless identifiers for codes
but maybe there are sufficient advantages that we don't actually regret have chosen to use meaningful strings for codes - but the fact that we did does tend to lead to the occurrence of situations like this, as Alexander said
Lloyd McKenzie (Aug 15 2018 at 21:15):
After discussion w/ Grahame and some digging, this is not actually a spelling "error". There's a common spelling and a less common spelling. Both are permitted. I'm therefore less enthusiastic about making the change.
Rob Hausam (Aug 15 2018 at 21:16):
the problem is more of the inconsistency in use (we have it both ways) rather than which is the "correct" spelling
Grahame Grieve (Aug 15 2018 at 21:16):
@Robert McClure do you think that VSAC will support R3 value sets, or R4 value sets, or both, if we make this change?
Rob Hausam (Aug 15 2018 at 21:18):
we could make them all consistently "descendent" if we wanted to (not sure why we would), but to do that some would still need to change
David Hay (Aug 15 2018 at 21:18):
We've just had a discussion on this at the FMG meeting. Our leaning is to go with the original spelling, on the grounds that it is not "wrong" - it's just not as "right" as the corrected one, and that the downstream impacts of making the change significantly outweigh the value in making it. (There's no perfect answer unfortunately).
David Hay (Aug 15 2018 at 21:18):
especially given that this is a Normative candidate...
Grahame Grieve (Aug 15 2018 at 21:19):
Rob - every other use of the word that we have is narrative only. This is the only place where change means anything
David Hay (Aug 15 2018 at 21:19):
Our hope is that ballot voters will appreciate this position...
Grahame Grieve (Aug 15 2018 at 21:19):
FMG also discussed asking TSC to rule on this if the vocab co-chairs do ask to keep the change
Grahame Grieve (Aug 15 2018 at 21:19):
as for conversion code: yes, it's true that 'we' have ode to convert between resources. that is: I maintain open source java code to do so (and use it extensively in the IG publisher and validator). I also maintain structuremap conversion routines between the versions.
Rob Hausam (Aug 15 2018 at 21:20):
I'm not sure that they actually will in the long run, as I've mentioned - but we can see
Rob Hausam (Aug 15 2018 at 21:20):
right
Grahame Grieve (Aug 15 2018 at 21:20):
few people can make use of those. In fact, I am only aware of 2 other groups using either at this point, though more people make use of the structure maps as documentation
Grahame Grieve (Aug 15 2018 at 21:21):
more to the point, ROb, how would you use my conversion code to manage this change? I think that's not an easy answer
Rob Hausam (Aug 15 2018 at 21:24):
I guess the answer to that depends on exactly what needs to be converted between R3 and R4 - it seems likely doable for resource instances (but presumably the terminology conversion would need to be added - at least I don't recall that it is already there)
but it obviously wouldn't automatically fix issues for tool developers
Michael Lawley (Aug 15 2018 at 21:27):
As soon as we update snapper to support R4, we would update the handling of this code; we already do this type of thing for DSTU2.1 STU3 changes
Grahame Grieve (Aug 15 2018 at 21:27):
so you would support R4 only? or both? if you support both, how would you support it?
Rob Hausam (Aug 15 2018 at 21:28):
I think something similar to what Michael just said is likely to be true for others (but I can't speak for them)
Rob Hausam (Aug 15 2018 at 21:38):
I just thought a little bit more about what David said: "Our leaning is to go with the original spelling, on the grounds that it is not "wrong". So, if it actually was "wrong" (i.e. if it was a misspelling that isn't truly a word rather than an unintended and inconsistent actual word that was chosen, that FMG then would be in favor of making the change (even with the arguments that have been raised)? That seems like a rather weak position to me. If you could make the change in the one case I think you could do it in the other. And, if not, don't make the change in either case - just treat the strings as if they were meaningless identifiers.
Rob Hausam (Aug 15 2018 at 21:45):
An alternative proposal along the lines of what Grahame's comment that "every other use of the word that we have is narrative only" might imply would be to change it to be "descendent" in all of the other places so it's consistent. If we're not unhappy (enough) with the not as "right" word, then I think that would actually be better.
Grahame Grieve (Aug 15 2018 at 21:47):
it's your desire for consistency that puts the degree of mis-spelling on the table
Rob Hausam (Aug 15 2018 at 21:49):
From the English perspective I'm not fond of it, and I think it would seem slightly weird, but at least it would be consistently weird. And maybe we could claim that the Australians say it that way. :)
Rob Hausam (Aug 15 2018 at 21:49):
or is it New Zealanders? :)
Rob Hausam (Aug 15 2018 at 21:50):
Sorry, I couldn't quite resist that. My preference is for both consistency and "correctness" - but if we can't have both we could at least have one?
Grahame Grieve (Aug 15 2018 at 21:51):
we can say that the product director uses it that way ;-)
Rob Hausam (Aug 15 2018 at 21:51):
ok - that makes sense :)
Rob Hausam (Aug 15 2018 at 21:55):
I keep thinking that I'm going to say only one more thing (and maybe this will be it) - but if we find ourselves feeling uncomfortable with changing to use "descendent" in the narrative references (and I don't know that we do) that might tell us something.
Michael Lawley (Aug 15 2018 at 22:32):
We support both by detecting the FHIR version in the server when you Create/Update the ValueSet and then adjusting accordingly
Michael Lawley (Aug 15 2018 at 22:42):
I'm quite liking the invocation of the "meaningless identifier" angle; change the human facing description/display but leave the code itself alone.
Michael Lawley (Aug 15 2018 at 22:44):
The various code libraries could then decide whether to expose the identifier or the label as the Enum name
Rob Hausam (Aug 15 2018 at 22:47):
I hadn't quite thought of it going to that full extent, but that may make the most sense
another example of why Cimino was right :)
Rob Hausam (Aug 15 2018 at 23:05):
At the end of this discussion, I like it, too (and I already agreed with the principle). And we may end up wanting to go farther down the "meaningless identifier" road in the future. I'm not quite sure how that fits with "normative", but if it's handled in the code libraries maybe that works.
Lloyd McKenzie (Aug 15 2018 at 23:19):
Meaningless identifiers in instances for things that developers will need to write 'switch' statements on isn't reasonable. I'd much rather have typos in the specs for 50 years than have something like this appear in the code case '98746112': ....
Rob Hausam (Aug 15 2018 at 23:28):
That makes some sense. I think for code systems and value sets that are expected to be used in logic such as 'switch' statements the codes can be readable. But we will still want to treat them from a terminology perspective as meaningless identifiers (as where we seem to be landing in this current discussion). That's likely the best "middle ground" position that I can see.
Grahame Grieve (Aug 16 2018 at 00:19):
they are meaningless identifiers if you don't speak english. And we say that you SHOULD always show the display not the code (except for debugging purposes)
Rob Hausam (Aug 16 2018 at 00:20):
agree
Grahame Grieve (Aug 16 2018 at 00:20):
they are meaningful only in that they orient you to the specification directly.
Robert McClure (Aug 16 2018 at 18:19):
@Grahame Grieve RE: R3/R4 support - I'll need to ask but FHIR support in general has been tangential to other work, so not well resourced. If I had to guess, suspect they will migrate to R4 and leave R3 behind.
Grahame Grieve (Aug 16 2018 at 19:03):
where as if we don't make this change... it won't matter
Grahame Grieve (Aug 16 2018 at 23:35):
ok I rolled this change back.
Rob Hausam (Aug 16 2018 at 23:45):
based on earlier premises I argued differently, but I'm happy with where we landed
the code is still a little weird with the "wrong" word, but as a meaningless identifier that doesn't matter
Grahame Grieve (Aug 16 2018 at 23:46):
it's one of those 'least worst' types of outcomes
John Carter (Aug 17 2018 at 04:37):
And a case study in why standards development is not for the feint of hart. Every letter kinda matters.
Last updated: Apr 12 2022 at 19:14 UTC
