Stream: implementers
Topic: custom operation naming
Jens Villadsen (Aug 06 2020 at 09:31):
Whats the preferred naming scheme for custom FHIR operations?
- camelCase
- PascalCase
-
snake_case
or -
kebab-case
Marian Hummel (Aug 06 2020 at 09:37):
@Jens Villadsen https://wiki.hl7.org/FHIR_Guide_to_Designing_Resources
Names for operations, resources and resource elements must:
be lowerCamelCase for elements, UpperCamelCase for resources, be lowercase for operations
Jens Villadsen (Aug 06 2020 at 09:56):
Let us take this to another level - and let me be a bit more specific (as I actually meant OperationDefinition.code since that's the name used for invocation).
- The example http://hl7.org/fhir/r4/operation-library-data-requirements.json.html uses kebab-case in its OperationDefinition.code
- I can't see that OperationDefinition.code being flagged as a warning if it does not adhere to those rules
- If it is a rule that is to be followed, shouldn't there then be an invariant guarding this rule?
Jens Villadsen (Aug 06 2020 at 09:56):
@Grahame Grieve @Marian Hummel
Grahame Grieve (Aug 06 2020 at 11:20):
I don't know about an invariant. It's true that we've used 'kebab-case' (never heard that before!). I don't know that we should make any hard rules about it
Jens Villadsen (Aug 06 2020 at 11:24):
https://confluence.hl7.org/pages/viewpage.action?pageId=35718826#GuidetoDesigningResources-NamingRules&Guidelines says must
The suggestion about invariant could just be a warning, if there really is a preference that people should follow.
image.png
Grahame Grieve (Aug 06 2020 at 11:28):
yeah could be.
Jens Villadsen (Aug 06 2020 at 11:57):
you want a JIRA for that?
Lloyd McKenzie (Aug 06 2020 at 14:41):
Sure
Jens Villadsen (Aug 06 2020 at 21:44):
done - https://jira.hl7.org/browse/FHIR-28222
Jens Villadsen (Nov 09 2020 at 22:14):
So ... @Grahame Grieve I see that the status just got updated (and commenting in JIRA is apparently disabled - don't know why?!). How come the invariant check was postponed / discarded / abandoned ?
Jens Villadsen (Nov 09 2020 at 22:15):
Are you going to rephrase the text on https://confluence.hl7.org/pages/viewpage.action?pageId=35718826 instead - or should I (as it is directly editable) ?
Josh Mandel (Nov 10 2020 at 17:41):
@Lloyd McKenzie do we intentionally prevent comments on closed issues? It'd be nice to keep these open.
Josh Mandel (Nov 10 2020 at 17:43):
@Jens Villadsen in discussion yesterday, we agreed that lack of implementer awareness was the biggest issue and the easiest to fix, so we started with docs links. We were concerned that writing constraints would be brittle / hard to get right, and would be likely to generate spurious errors.
Lloyd McKenzie (Nov 10 2020 at 17:56):
Yes, we do. Because most work groups don't monitor closed issues, so comments raised there are likely to be ignored. "managers" (co-chairs, etc.) are able to put comments on issues that are resolved, change required. Once things get to Applied, or any of the other 'end' states, commenting is no longer possible without re-opening.
Jens Villadsen (Nov 10 2020 at 17:59):
@Josh Mandel I'm puzzled. Are you actually saying that you intend to update the OperationOutcome doc and have that doc pointing to the page on confluence?
Jens Villadsen (Nov 10 2020 at 18:01):
@Lloyd McKenzie FYI - I somewhat understand your current practice - it however could be perceived wrongly - as a closed forum where comments are not welcom.
Jens Villadsen (Nov 10 2020 at 18:02):
I haven't observed such configuration before in a JIRA setup
Josh Mandel (Nov 10 2020 at 19:10):
. Are you actually saying that you intend to update the OperationOutcome doc and have that doc pointing to the page on confluence?
That's right -- this is what we agreed to yesterday.
Lloyd McKenzie (Nov 10 2020 at 19:25):
Comments that are likely to be ignored aren't welcome. Anyone with an account is free to create a new issue referencing the existing resolved one if they think there's a need to revisit.
Jens Villadsen (Nov 10 2020 at 19:59):
@Josh Mandel you guys really think that is a great idea? Your proposal to link to a site with no governance (which I just edited - see https://confluence.hl7.org/pages/viewpreviousversions.action?pageId=35718826) brings the link of little value. Why not put the content directly into the spec (which at least have a ballot and governance proces?
Jens Villadsen (Nov 10 2020 at 20:05):
@Lloyd McKenzie I don't see the possibility to reference an existing JIRA issue when creating a new JIRA issue (besides an actual hardcoded link to it). Which field would that be?
Josh Mandel (Nov 10 2020 at 20:48):
your proposal to link to a site with no governance
this kind of editorial guidance exists entirely outside of the spec; the same considerations apply for naming conventions on core resources, etc. The goal of adding links is just to make sure that readers are aware that guidance exists.
Lloyd McKenzie (Nov 10 2020 at 20:49):
Methodology around resource design doesn't belong in the spec. The FHIR spec is targeted at implementers, not the HL7 work groups that design the spec. We put a few design documents into the spec, but only if they have a strong impact on implementers. E.g. FMM levels.
Lloyd McKenzie (Nov 10 2020 at 20:50):
Also, methodology needs to be able to evolve independently of the FHIR publication cycle
Jens Villadsen (Nov 10 2020 at 21:10):
@Josh Mandel naming conventions for eg. core resources is much different from naming custom operations which probably (wild guess) occur with a x500 factor. The guideline/methology says must now (that was my change to add italic and bold). Shouldn't such a must end up in the spec - or should the wording be changed?
Jens Villadsen (Nov 10 2020 at 21:10):
I find it complicated to have such bold statements outside the spec
Lloyd McKenzie (Nov 10 2020 at 21:11):
Those are rules that apply to HL7 authors. They don't necessarily apply to everyone. Rules that apply to everyone would indeed be expected to appear in the FHIR spec.
Jens Villadsen (Nov 10 2020 at 21:13):
wait a moment ... those rules are for authoring resources to/in the FHIR spec?
Jens Villadsen (Nov 10 2020 at 21:13):
and not rules/suggested rules for eg. IG authoring?
Lloyd McKenzie (Nov 10 2020 at 21:38):
Correct. Those are rules for work groups defining the core spec. They may be relevant to others when designing profiles/IGs, but that's not what they're written for.
Jens Villadsen (Nov 10 2020 at 22:08):
okay that changes pretty much everything
Jens Villadsen (Nov 10 2020 at 22:11):
in that case I'll suggest to enhance the Igpublisher with a -followTheRules flag where one can get a bunch of warnings for not following the policies for eg. operation naming
Jens Villadsen (Nov 10 2020 at 22:13):
FYI - @Marian Hummel - the rules you originally referred to probably have another scope than you thought
Jens Villadsen (Nov 10 2020 at 22:16):
and just for clearing out the naming: what casing is prefered?:
- camelCase
- PascalCase
-
snake_case
or -
kebab-case
Lloyd McKenzie (Nov 10 2020 at 22:22):
For operation names? We're not even consistent in FHIR core. In general we try to avoid case sensitivity in URLs because that tends to cause grief
Jens Villadsen (Nov 10 2020 at 22:23):
so we're down to snake_case or kebab-case
John Moehrke (Nov 10 2020 at 22:24):
makes me hungry... and also wondering what a kebab camel tastes like
Last updated: Apr 12 2022 at 19:14 UTC
