Stream: fmg
Topic: Custom Resource Policy
Grahame Grieve (May 01 2016 at 03:42):
first draft for discussion:
Grahame Grieve (May 01 2016 at 03:42):
http://wiki.hl7.org/index.php?title=FHIR_Custom_Resources
Lloyd McKenzie (May 01 2016 at 03:51):
So we're not going to differentiate between someone who's introducing a resource that FHIR doesn't cover (i.e. mostly interoperable with FHIR) from those who are introducing alternative models for conveying content FHIR already supports (i.e. what openEHR would like to do)?
Lloyd McKenzie (May 01 2016 at 03:51):
I'd really like us to have that differentiation.
Grahame Grieve (May 01 2016 at 11:15):
differ how? I'm not against having such a differentiation but I don't know where you'd make it, or how you'd decide whether it was. Sometimes it might be obvious but other times not at all
Lloyd McKenzie (May 01 2016 at 14:34):
It would have to be done at the time of applying for a name or namespace. Applications for namespaces would automatically be considered to fall in the "overlapping" space. Applications for names could indicate whether they intended to overlap. If the intention was not to overlap, then the review process would check that. And we could have a conformance level for "extended FHIR" which would have a schema that would include all of the "extension" resource names with content models of xs:any that they could validate against. Obviously there will be some edge cases where overlap would be unclear and it would also mean additional workload, but I think it's worth trying.
Lloyd McKenzie (May 01 2016 at 14:35):
On a separate note, I think the review should be CTO, Product Line Manager or their delegate. There's a lot of jobs on both of your plates and I'd really rather we be removing stuff from that list, not adding to it.
Grahame Grieve (May 01 2016 at 15:58):
the policy does say that you have to declare your intent. I'm not sure what procedures you have in mind to enforce that
Josh Mandel (May 01 2016 at 16:11):
Just to test my understanding of what you've written:
All these names come out of the same namespace,
Meaning (in current parlance) that all resources will have canonical URLs like http://hl7.org/fhir/StructureDefinition/{{name}} ?
Grahame Grieve (May 01 2016 at 16:12):
yes
Grahame Grieve (May 01 2016 at 16:12):
oh no. hang on
Josh Mandel (May 01 2016 at 16:12):
Hmm, doesn't that cause custom resources names to clash?
Josh Mandel (May 01 2016 at 16:12):
Would we just have a second base like http://fhir.org/CustomStructureDefinition/ ?
Grahame Grieve (May 01 2016 at 16:12):
the point is, because of the various places in which names appear, they can't clash
Grahame Grieve (May 01 2016 at 16:12):
part of this policy ensures that they don't
Josh Mandel (May 01 2016 at 16:13):
I understand the intent, but not the mechanics (yet).
Grahame Grieve (May 01 2016 at 16:13):
the canonical URL of the structure definition varies according to publisher, but the root comes from a common namespace anyway
Grahame Grieve (May 01 2016 at 16:14):
get http://acme.com/fhir/[CustomName]/123
Josh Mandel (May 01 2016 at 16:14):
What does "root" mean? The term doesn't appear in http://wiki.hl7.org/index.php?title=FHIR_Custom_Resources or http://hl7-fhir.github.io/structuredefinition or http://hl7-fhir.github.io/elementdefinition
Grahame Grieve (May 01 2016 at 16:15):
sorry, the root = 'the actual name of the resource'. wrong term to have used
Josh Mandel (May 01 2016 at 16:16):
So let's say SMART defines an AppManifest resource describing application metadata. What is the canonical URI? What is the "actual name"?
Grahame Grieve (May 01 2016 at 16:16):
AppManifest is the actual name. The canonical URL is whatever you publish at
Josh Mandel (May 01 2016 at 16:16):
And later someone else wants to define an AppManifest resource describing, um, applicable manifestations of a disease (I'm reaching here but bear with me).
Josh Mandel (May 01 2016 at 16:16):
They can't do this, because we already "grabbed" the name, even though their canonical URL would be different?
Grahame Grieve (May 01 2016 at 16:17):
yep that's right.
Josh Mandel (May 01 2016 at 16:17):
And if HL7 wants to define such a construct offically, they also can't?
Grahame Grieve (May 01 2016 at 16:17):
well, no. Becuase of this bit:
Grahame Grieve (May 01 2016 at 16:18):
"all custom resource names will include at least one character '-' or '.',"
Grahame Grieve (May 01 2016 at 16:18):
which means, yes, you couldn't use 'AppManifest', you'd have to use 'smart.AppManifest' or something
Josh Mandel (May 01 2016 at 16:18):
Right, OK. Would help to include some examples in the doc to spell this out. I'd argue that we really should use the "prefix" strategy exclusively.
Grahame Grieve (May 01 2016 at 16:19):
I forgot that bit earlir
Josh Mandel (May 01 2016 at 16:19):
(No problem, that makes more sense.)
Grahame Grieve (May 01 2016 at 16:19):
and I did intend to do that, agree it would be good to spell that out more than just that slightly obscure sentence
Josh Mandel (May 01 2016 at 16:21):
But overall, registering prefixes makes more more sense to me.
Grahame Grieve (May 01 2016 at 16:21):
I would expect that most things would happen that way
Josh Mandel (May 01 2016 at 16:22):
I have to say that for me, the "good thing" that FHIR offers is a core set of resources that drive community agreement.
The modeling framework itself is a different kind of thing (I recognize that others value it very highly, and that it represents a tremendous amount of work!)
Grahame Grieve (May 01 2016 at 16:23):
I figured, when I was writing the policy, that this is the obvious case to register the name rather than the prefix: "prototyping resources that will be brought to HL7 to be part of the specification"
Josh Mandel (May 01 2016 at 16:23):
Given this: I worry that "Custom FHIR" will erode FHIR's core value (IMHO) while expanding the most complex parts that few people can understand.
Grahame Grieve (May 01 2016 at 16:23):
yes, lots of people worry about a lot - reflected in Lloyd's first comment
Grahame Grieve (May 01 2016 at 16:23):
and I agree completely
Josh Mandel (May 01 2016 at 16:23):
Lloyd is saying something a bit different though.
Josh Mandel (May 01 2016 at 16:24):
He's expressing concern about eroding FHIR's core value, yes -- but not the second part (encouraging people to focus on the complex parts that they won't understand)
Grahame Grieve (May 01 2016 at 16:24):
you haven't been on the phone calls where we've discussed this - people feel very strongly about it. But there's real communities that want to do this too, and the alternative is to reject them
Josh Mandel (May 01 2016 at 16:24):
Yes, I get that!
Grahame Grieve (May 01 2016 at 16:26):
on the other hand, the machinery to set this up is the complex bit, and would generally be executed by tooling, and consumers would generally not be exposed to the complex bits, only the tool smiths
Josh Mandel (May 01 2016 at 16:27):
I disagree on this part -- I think the complexity leaks out to everyone working with these resources, not just those authoring them. First off, keeping track of builds of your tools, client libraries, validators, etc that support the relevant sets of custom profiles.
Grahame Grieve (May 01 2016 at 16:29):
ok that's more complex, but it's not the real complexity. In practice, the owners of the prefixes/names need to distribute definition packs. Anyone who uses the conformance resources just also loads the definition packs.
Grahame Grieve (May 01 2016 at 16:29):
it absolutely makes the version tracking etc and reference implementations harder, that's for sure
Grahame Grieve (May 01 2016 at 16:30):
though I think that if you don't want to get involved in custom resources, it doesn't change anything
Josh Mandel (May 01 2016 at 16:30):
Yes -- and my point isn't "this can never work". It's more that we haven't exactly sorted out these issues in the current FHIR world-view.
Josh Mandel (May 01 2016 at 16:30):
And now it gets harder.
Grahame Grieve (May 01 2016 at 16:31):
yes
Paul Knapp (May 01 2016 at 17:45):
My recollection of the Tursday meeting in Orlando was that we had agreed to registering prefixes.
Grahame Grieve (May 01 2016 at 19:04):
that's a strange recollection since we didn't discuss it in Orlando
Grahame Grieve (May 01 2016 at 19:04):
hmm maybe we did but not in that detail, I thought
Paul Knapp (May 01 2016 at 19:12):
Sure we did - namespace vs prefix.
Grahame Grieve (May 01 2016 at 19:15):
I think that might have been a slightly different context? but it wasn't prefix vs name, which I thought you were referring to
Paul Knapp (May 01 2016 at 19:20):
The real choice was between names adn namespaces, but namespaces are problematic, so names were the loose choice. This it was do we use a prefix or suffix for just register all names and allow themto interleave. Reserving of prefixes makes sense then you just need to let the registratnt assign names with the prefix.
Paul Knapp (May 01 2016 at 19:21):
This was more of a bluesky discussion.
Grahame Grieve (May 01 2016 at 19:21):
well, the policy as proposed allows either to register a name, or a prefix. As it stands, it's more onerous to register a prefix, because you have to indicate owner organisation and make some policy statements
Lloyd McKenzie (May 02 2016 at 00:37):
If the resource definition (or even the introductory paragraph defining scope) needs to be submitted when requesting individually named resources, that should let us check for overlap of scope. If you want to have "Extended FHIR" compatibility, requesting individual resource names would be your only option. If you just register prefixes, you're stuck with "Custom FHIR". Though I think I prefer "FHIR-inspired" or something. "Custom" doesn't necessarily convey "not intereoperable" as strongly as I'd like
Grahame Grieve (May 02 2016 at 02:29):
there
Grahame Grieve (May 02 2016 at 02:29):
there's 2 different issues there - name, and policy
Grahame Grieve (May 02 2016 at 02:30):
I chose to say that if you create custom resources, you're not FHIR comformant for a reason: there's no judgement about that call - it's fact. And it conveys the idea that if you create a custom resource, then there's no expectation that a FHIR conformant system will handle it or understand it properly
Grahame Grieve (May 02 2016 at 02:31):
this is true whether you're ignoring the standard resources or not - and whether you are or not will often be completely unclear
Grahame Grieve (May 02 2016 at 02:32):
I don't have an opinion about the name, except that I chose 'custom fhir' because I suspect that this is going to self-naming whether we like it or not
Lloyd McKenzie (May 02 2016 at 02:49):
If I introduce one custom resource (say 'Study') because we all agree that Basic sucks, but everything else I do is FHIR conformant, then I should be able to interoperate with most systems quite well. Ideally we'd have one "special" prefix for such resources and the reference implementations could treat them all like Basic internally.
Lloyd McKenzie (May 02 2016 at 02:50):
That's a very different thing from someone who's sending OpenEHR models over the wire - no hope of them interoperating with someone who's done a standard FHIR implementation.
Lloyd McKenzie (May 02 2016 at 02:50):
Really, all we're doing is providing a variant way of doing Basic in the first case.
Grahame Grieve (May 02 2016 at 02:51):
who's going to decide? Is Lloyd the determinate?
Lloyd McKenzie (May 02 2016 at 02:52):
Who's going to decide whether the scope of a resource overlaps an existing resource? You or the CTO or your delegate would make the first call. If we need an escalation process, FMG would be the next logical stop.
Grahame Grieve (May 02 2016 at 03:05):
so if you get a prefix, you still need to offer every version of every resource to HL7 for review?
Lloyd McKenzie (May 02 2016 at 03:07):
If you get a prefix, you're out of luck - you're in the "FHIR-inspired" camp. The only way interoperability with everyone else works is if there's a standard prefix and we curate not just the names but the scope. If that doesn't work for you, then you're not going to interoperate. And realistically, if you're wanting to play nicely with the existing content, you're not going to need your own prefix. There's likely only 2-3 new "special" resources you're going to need.
Paul Knapp (May 03 2016 at 09:18):
Would it help to say that all custom resources MUST have prefix, either a registered prefix which only the registrant may use or a general prefix which anyone may use, followed by '.' or '-' followed by the name which may include additional '-' and '.'.?
Grahame Grieve (May 03 2016 at 10:39):
we say exactly that. But I don't think it makes a difference to this discussion
Grahame Grieve (May 03 2016 at 10:39):
it turns out - based on implementation experience - that there's something else to say about this... it makes a difference whether there's a bi-directional map to real resources.
Josh Mandel (May 03 2016 at 12:27):
Can you say more about this bidirectional mapping issue? Is it to address custom resources defined as "views" on existing data sets?
Grahame Grieve (May 03 2016 at 13:02):
well, if you define a custom resource, or a logical model (not sure what the difference is in some ways), and you define a bi-directional mapping to resources, then, yes, the server can express custom resources while actually also making them available as normal resources
Grahame Grieve (May 03 2016 at 13:03):
and/or some client library or network service can do it as a view thing
Grahame Grieve (May 03 2016 at 13:03):
the hard lines collapse if anyone can interconvert...
Grahame Grieve (May 03 2016 at 13:04):
though I have been thinking about what an API to a logical view of a set of resources would look like - that might address some of the desire for custom resources anyway.
Grahame Grieve (May 03 2016 at 13:04):
as an example, take this:
Grahame Grieve (May 03 2016 at 13:04):
http://hl7-fhir.github.io/nehta/nehta-shared-health-summary.html
Grahame Grieve (May 03 2016 at 13:05):
that has mappings in an executional language to resources
Grahame Grieve (May 03 2016 at 13:05):
so you could POST a shared health summary to base/Logical, for instance, and the server would actually store the resources
Grahame Grieve (May 03 2016 at 13:06):
but it's not obvious to me how you'd get a logical model, and how you search for it - if that was necessary.
Lloyd McKenzie (May 03 2016 at 14:51):
If anyone can convert, why should we allow the "rogue" syntax to be exchanged by conformant instances?
Lloyd McKenzie (May 03 2016 at 14:51):
If you want to do it via private interface, no-one's stopping you. If you want to be conformant, run the transform at each end - so you're not imposing on otherwise-conformant recipients
Grahame Grieve (May 03 2016 at 15:34):
well, if it's a good practical idea, perhaps there's a way to bake it in and make it conformant
Grahame Grieve (May 05 2016 at 06:01):
an alternative take on this is that we have this custom resource policy, but we do discuss the option of ignoring the existing resources, and we don't have any path by which that is conformant. But we do have a path by which it is possible
John Moehrke (May 10 2016 at 13:05):
What is it that we are trying to enable? I am not aware of the discussions with OpenEHR, so I might be lacking critical information to help inform my decision. Anyone can define any RESTful resource, FHIR doesn't have a lock on all possible RESTful resource names. We have conventions, and process to support 'standard' FHIR Resources. I fail to understand why we would do anything non-standard.
Grahame Grieve (May 10 2016 at 13:09):
well, you might argue, then, from that perspective, that we should not do extensions, etc. But we do, because we understand that there are good reasons to extend the specification, and providing guidance about how to do consistently without running into problems is a positive good for a number of implementers
John Moehrke (May 10 2016 at 13:16):
Yes, I am arguing that registering custom resources and extensions is something beyond HL7, a 'standards' organization... not necessarily beyond fhir.org, an 'implementation support' organization. What I am trying to understand the motivation. Your response regarding extensions seems evasive... which is more troubling for me. Yes I might be unnecessarily worried, but it seems reasonable that I can ask the question and get an answer.
Lloyd McKenzie (May 10 2016 at 18:35):
Well, it ties into the implementation space. If there's a way to register "custom" resources that will mix with "standard" resources such that systems using the reference implementations, etc. can handle them, that would be good. And that mechanism, if it's to exist, is HL7's concern. Supporting totally off-reservation implementations like OpenEHR is distinct from that. There it's just a question of saying what language we'd expect them to use. And the leaning at FGB this morning was to say that we'll exclude that particular usage aspect entirely from the proposal. So this proposal would be limited to allowing resource names to be defined for content that doesn't yet exist in FHIR in a way that will prevent collisions and allow systems to manage things like "Ex-ClinicalStudy" or "Ex-BillingItem" in parallel with Observation, Encounter, etc. when those resources don't yet exist (or might never exist) in the FHIR spec.
Grahame Grieve (May 10 2016 at 19:04):
I didn't intend to be evasive.
Grahame Grieve (May 10 2016 at 19:05):
we routinely provide advice around customization and extension of the specificatin, and we routinely do this in Fhir too. So this is just more of that
Lloyd McKenzie (May 10 2016 at 19:43):
I think of the non-OpenEHR part of it is "Let's come up with an alternative to Basic that everyone doesn't hate".
Grahame Grieve (May 10 2016 at 19:45):
I just saw a use of Basic in the wild
Lloyd McKenzie (May 10 2016 at 19:46):
Cool. Was it as ugly as we predicted?
Grahame Grieve (May 10 2016 at 19:47):
shallow, so not too bad
Grahame Grieve (Jul 08 2016 at 04:14):
I updated the custon resource policy to define custom resources precisely. http://wiki.hl7.org/index.php?title=FHIR_Custom_Resources
Grahame Grieve (Jul 08 2016 at 04:15):
I also found that I needed to reference 'custom resources' - that page - at one specific place in the specification
Grahame Grieve (Jul 08 2016 at 04:15):
rules around use of ElementDefinition
David Hay (Jul 08 2016 at 04:29):
What's the timeline for your server supporting custom resources?
David Hay (Jul 08 2016 at 04:30):
and - technically - a 'logical model' is the same as a custom resource, except it's not intended to be used in production - right?
Brian Postlethwaite (Jul 08 2016 at 04:51):
This will result in "Custom" appearing in the ResourceTypes enumerations (specifically in conformance) right?
(asking so that client's can stil read the conformance resource from your server and be able to process that part)
Grahame Grieve (Jul 08 2016 at 05:27):
umm, we haven't resolved the question of logical models and the type enumerations
Grahame Grieve (Jul 08 2016 at 05:29):
David, here's the differences between custom resources and logical models:
- StructureDefinition.kind is different (resource vs logical)
- A custom resource must inherit from 'resource', a logical model must inherit from 'element'
- a custom resource can only refer to fhir defined data types for types. A logical model can use other logical models as types
Grahame Grieve (Jul 08 2016 at 05:30):
a logical model can have a wire format - see http://fhir.hl7.org.au/fhir/rcpa/Colorectal-Colorectal-genexample-1.xml.html - but it can't appear in the 3 places I identified in the custom resource policy
Grahame Grieve (Jul 08 2016 at 05:30):
that's not the same as 'not used in production'
Grahame Grieve (Jul 08 2016 at 05:31):
timeline - I don't know, custom resources actually work on my server, but I haevn't finished doing all the support work on them
David Hay (Jul 08 2016 at 05:39):
thanks for the clarification!
Brian Postlethwaite (Jul 08 2016 at 05:40):
I pointed the enumeration as it shows up in failed unit tests on the dotnet client in DSTU2 (which some get nervous about) though its really just it is encountering the "custom" type on your DSTU2 endpoint.
Brian Postlethwaite (Jul 08 2016 at 05:40):
(and STU3 from May also)
Grahame Grieve (Jul 08 2016 at 05:40):
the custom type?
Brian Postlethwaite (Jul 08 2016 at 06:14):
I'll go recheck and follow up elsewhere. (not FMG)
John Moehrke (Jul 08 2016 at 13:14):
@Grahame Grieve I recommend you move the section titled "How custom resources work, technically" up and rename it "Definition of Custom Resource". Your section "Custom Resources" should then follow with "Uses of Custom Resources".
John Moehrke (Jul 08 2016 at 13:17):
Your first section defining 1 and 2 is critical and I think need more highlighting. The key I now understand is that a custom resource is one that uses what you call the framework, but is not a further defined in FHIR. Thus I think we need a distinguishing word for this FHIR Framework; possibly needing to separate it out into a independent specification.
John Moehrke (Jul 08 2016 at 13:18):
Do you expect systems that don't 'understand' a custom resource to pass it unmodified? Or are they allowed to drop it? I didn
Grahame Grieve (Jul 08 2016 at 21:02):
I expect them to drop them - see this: "Obviously, only implementers that know the particular custom resources will be able to partake in exchange using the custom resources"
Grahame Grieve (Jul 08 2016 at 21:04):
I reorganised the page a little
Lloyd McKenzie (Jul 09 2016 at 04:46):
Implementers that have a persistence layer that's designed to support FHIR ought to be able to handle custom resources easily enough - just convert them to Basic and capture the profile that identifies what type of custom resource they are for subsequent re-serialization. But anyone who has a legacy data store would have trouble persisting them unless they have the capability to store blobs of some sort
Grahame Grieve (Jul 09 2016 at 07:42):
man that would be the hardest way to do it! if yo're clever enough to parse a custom resource from metadata, you should be able to store it
John Moehrke (Jul 10 2016 at 18:06):
It would also be hard to secure them without understanding them. All you would know is what the meta tags tell you, and those would need to have been applied properly by the creator/updater. Right? If so, then custom resources would also need to have a security consideration warning about this. I don't see it it as a big problem, just wanting it noted.
Grahame Grieve (Jul 10 2016 at 20:37):
yes that'a a good point
Last updated: Apr 12 2022 at 19:14 UTC
