Stream: implementers
Topic: CapabilityStatement
Shovan (Apr 23 2017 at 08:46):
Hi All, I am currently working on creating a sample CapabilityStatement and I am considering STU 3.0.1. To make progress on it, I need few clarifications on CapabilityStatement resource (http://hl7.org/fhir/capabilitystatement.html). May I request the group to help me understand the following points:
1. How to structure 'CapabilityStatement.rest' ? Is it recommended that per 'server' there will be only one 'rest' element ('CapabilityStatement.rest') and all the resources ('CapabilityStatement.rest.resource') exposed by the server will be residing under that element ? According to my understanding, there will be one 'CapabilityStatement.rest' element per api (resource) that the server is exposing. For an example if my server is exposing 'Patient' and 'ExplanationOfBenefit' as to different rest interfaces, then in my CapabilityStatement, there will be two 'CapabilityStatement.rest' elements and each of them should contain a resource (Patient/EOB). However looking at the samples (http://hl7.org/fhir/capabilitystatement-examples.html), it seems like all the resources will go under one rest element.
2. If the model doesn't support dedicated 'rest' element per resource in the CapabilityStatement, then, :
1. How can I find out a custom operation which is applied to a particular resource by looking at the CapabilityStatement without reading the corresponding OperationDefination for that resource?
2. From the 'CapabilityStatement' how would I know that the server is implementing varying subset of common search paramaters (e.g.: '_id') for different rest interfaces ?
3. From the 'CapabilityStatement' how would I know if the server is implementing http/https for the 'rest' interface? I can see 'CapabilityStatement.messaging.endpoint.protocol' has one.
4. In the 'CapabilityStatement.rest.security' how would I specify urls to generate 'auth_code' or 'access_token'?
5. For the search paramater (CapabilityStatement.rest.resource.searchParam), how would I know whether a paramater is optional/mandatory? rather cardinality ?
6. I can see the element 'CapabilityStatement.profile', is there any way to to understand the custom extensions applied? I can see the cardinality is 0..*. I guess we should add all the custom extensions here. But just like we are explicitly mentioning the search paramaters for a resource, can we also provide an option to detail out (e.g.: name, description, path, cardinality etc.) the custom extensions here ?
Lloyd McKenzie (Apr 23 2017 at 15:26):
1. The only time you'll have multiple 'rest' elements is to describe both your client and server capabilities (some systems will act as both)
2.1. The only way to understand an operation you're not familiar with is to retrieve the OperationDefinition
2.2. In principle each resource should list every search parameter it supports, including _id
2.3. I think the presumption is what you use as the base url - so if you query https://somewhere.org/capabilities and you get a response, then it supports https. But I'm not positive on this one.
2.4. I don't think this is standardized
2.5. Not yet standardized. Typically the cardinality of search parameters is based on what other search parameters are required - and we found that this gets really complicated fast, so for now, we've left it for descriptive text
2.6. CapabilityStatement.profile indicates what profiles you can search by using the profile tag. It has nothing to do with what extensions are supported. To see those, look at CapabilityStatement.rest.resource.profile and retrieve the StructureDefinition
Shovan (Apr 24 2017 at 11:34):
Thanks @Lloyd McKenzie I have few more quires on top of your clarification
1. It sounds like the cardinality is 0..2 for rest. Is there any specific reason we shouldn't expose one rest interface per resource?
2. I have worked on couple of OperationDefinition, however I was wondering if I could get hold of the Operation applicable to resource type from the CapabilityStatement directly other than referning to the OperationDefinition.
3. What if I want read it the details from the capabilityStatement directly ( just like how it is structured for message) other than manupulating it from url
4. Any plan to add that in the capabilityStatement defination ?
5. Any plan to add that in the capabilityStatement definition ?
6. Thanks.. got it :)
Lloyd McKenzie (Apr 24 2017 at 14:50):
1. Cardinality is 0..2. There are some tooling issues with us being that explicit. The spec currently says you can only have one 'server' and one 'client' REST interface and I can't imagine why you'd want one per resource.
Lloyd McKenzie (Apr 24 2017 at 14:51):
2. You can get the name used and the URL, but for anything else, you'll need the CapabilityStatement
Lloyd McKenzie (Apr 24 2017 at 14:51):
3. Not really following the question
Lloyd McKenzie (Apr 24 2017 at 14:52):
4. No - there's too many different ways for security to be done, so this would likely be extensions space. That said, you're free to submit a change request and make your case for adding it to core.
Lloyd McKenzie (Apr 24 2017 at 14:53):
5. CapabilityStatement is already one of the most complex resources we have, so doubtful. However, feel free to come up with a proposal you think is workable and reflects what systems would actually need.
Shovan (Apr 26 2017 at 00:40):
thanks @Lloyd McKenzie for your comments and suggestions . this was very helpful. I will reaise task on # 2,4, 5
Aditya Joshi (Oct 24 2018 at 09:54):
Hi @Lloyd McKenzie
CapabilityStatement.acceptUnknown= element|extension|no|both
It means application can accept unknown elements. But writing any data element which is not in FHIR is done by "extension". Then what this "element" represents here in case of acceptUnknown. Not able to understand meaning or purpose of "element".
Vadim Peretokin (Oct 24 2018 at 12:54):
see http://hl7.org/fhir/codesystem-unknown-content-code.html#unknown-content-code-elements:
The application accepts unknown elements, but not unknown extensions.
Yunwei Wang (Oct 24 2018 at 15:31):
different versions
Lloyd McKenzie (Oct 25 2018 at 03:54):
It's a statement of forward compatibility. If you say you accept unknown elements then if new elements are added in a future version of the resource, you won't reject the instance because you don't recognize those elements. Note that this element was dropped from CapabilityStatement in R4.
Javier Espina (Feb 27 2019 at 16:43):
I am exploring how to use CapabilityStatement to express the capabilities of FHIR-capable systems that are defined beyond the FHIR spec. A concrete example would be a FHIR R4 Server that is also a PCHA Continua compliant server (Continua CDG H.812.5 profiles the use of FHIR thereby defining Continua Capabilities). In this context I am wondering:
Q1.When we have a FHIR Server can CapabilityStatement be used to also describe non-FHIR capabilities of the Server (e.g. Continua-defined capabilities)?
Q2. If the answer to Q1 is "yes", do I need 2 instances of CapabilityStatement (one for FHIR caps & one for Continua caps) or can I use just one?
Q3. Can CapabilityStatement be used to describe capability of a Server irrespective of whether it’s a native FHIR Server or not (e.g. a legacy system with a FHIR façade)?
Q4. The last note of http://hl7.org/fhir/capabilitystatement.html says "Other service-based use of resources: Due to the variability of these services, the CapabilityStatement resource does not attempt to describe service-based use of resources. The various service specifications will need to describe this usage in their own way.". It looks like this could be relevant info to answer some of the previous questions. However I don't understand the statement (I guess because I don't understand the concept "service-based use of resources"). Could someone clarify the statement?
Thanks!!!
Lloyd McKenzie (Feb 27 2019 at 16:58):
Technically you can use CapabilityStatement to do pretty much anything with extensions. One of the challenges we're going to be playing with in R5 is how to reasonably allow the specification of detailed behaviors via CapabilityStatement such that it doesn't grow bigger than it is and we don't have to define new resources for every new type of capability we might want to describe. Not fully landed yet though. Experimentation and feedback are certainly welcome.
Grahame Grieve (Mar 01 2019 at 11:44):
it possible for Continua to paste a particular capability statement, and say in the description that it includes particular obligations in regard to processing. Then, if you reference it in CapabilityStatement.instantiates, then you are claiming that you implement those obligations. To me, this sounds like the answer to your question
Javier Espina (Mar 06 2019 at 17:22):
@Lloyd McKenzie , @Grahame Grieve: thank you for your quick replies. They've shed some light. I'll need to look into this in further detail.
Grahame Grieve (Mar 06 2019 at 21:43):
and I see I wrote "Continua to paste a particular " when I should've written "Continua to publish a particular "
Dave Henderson (Jul 25 2019 at 10:58):
I have a chained search that is used to return values from a document bundle. Something like this:
Composition?subject.identifier=:nhs&subject.birthdate=:birthdate§ion=:section
I need a capability statement to support this search. Would something like this:
"searchParam": [
{
"name": "section",
"definition": "http://hl7.org/fhir/SearchParameter/Composition-section",
"type": "token",
"documentation": "Classification of section (recommended)"
},
{
"name": "subject",
"definition": "http://hl7.org/fhir/SearchParameter/Composition-subject",
"type": "reference",
"documentation": "Who and/or what the composition is about"
}
]
},
be suitable ? Not sure if I need to include serchparam for Patient to:
{
"type": "Patient",
"interaction": [
{
"code": "search-type"
}
],
"searchParam": [
{
"name": "identifier",
"definition": "http://hl7.org/fhir/SearchParameter/Patient-identifier",
"type": "token",
"documentation": "A patient identifier"
},
{
"name": "birthdate",
"definition": "http://hl7.org/fhir/SearchParameter/individual-birthdate",
"type": "date",
"documentation": "Multiple Resources: \r\n\r\n* RelatedPerson: The Related Person's date of birth\r\n* Person: The person's date of birth\r\n* Patient: The patient's date of birth"
}
]
}
or is there a way to define a searchparam for chained searches ?
Cheers
Lloyd McKenzie (Jul 25 2019 at 12:59):
You'll actually need to point to your own system-specific SearchParameter instances which will have derivedFrom links to the original HL7 parameter, but will also list the specific chaining paths you support.
Eric Haas (Jul 25 2019 at 18:28):
Look at US Core ig this done.
Eric Haas (Jul 25 2019 at 18:29):
I also overloaded the expectation extension on search parameter for implementation guide purposes
Eric Haas (Jul 25 2019 at 18:29):
Go the question way up too I don’t understand what cardinality has to do with search parameters.
Eric Haas (Jul 25 2019 at 18:30):
I think the expectation extension should be used there as well
Dave Henderson (Jul 26 2019 at 09:18):
Thanks @Lloyd McKenzie and @Eric Haas for pointers. I'll take a look at both options.
Grahame Grieve (Sep 22 2020 at 17:32):
FHIR-I have been discussing re-working the trial use portions of CapabilityStatement in R5. I've published a rough draft of what that might look like - see https://chat.fhir.org/#narrow/stream/179280-fhir.2Finfrastructure-wg/topic/Rework.20of.20CapabilityStatement for discussion
Vivek (Oct 06 2021 at 13:04):
Any tool to create CapabilityStatement instance with html content?
Lloyd McKenzie (Oct 06 2021 at 13:33):
Can you explain more what you're wanting to do @Vivek ?
Corey Spears (Oct 06 2021 at 14:58):
@Vivek , Looking forward to hear what you are looking for.
If it is a tool that can help you create a CapabilityStatement from scratch without having to text/hand edit json/xml, there is a python/Jinja tool out there that can take an xlsx file and convert it to a CapabilityStatement with text.div narrative (html content). All you have to do is fill out the included workbook spreadsheets. I have a version of this locally that I could share, but @Eric Haas (whom I believe built it) may know where a more recent version is available.
I have further extended those scripts such that it can take an already existing CapabilityStatement and create a nicely formatted text.div narrative. I am currently working on merging these two together (xslx input script and CapabilityStatement json script) so it is all handled in one tool.
I am also interested in how I can make this more available to the community at large. This seems like a good area of common need across all IGs and implementations that do not have specialized CapabilityStatement narrative requirements.
Eric Haas (Oct 06 2021 at 16:50):
I have made updates to it as well. I have not had a chance to look at @Corey Spears changes. I too would like to make it more available though.
Vivek (Oct 07 2021 at 11:28):
@Corey Spears This is exactly what I want. Can you please share the github location for this utility?
Vivek (Oct 07 2021 at 11:38):
@Lloyd McKenzie I want to create a rich human readable CapabilityStatement instance.
Lloyd McKenzie (Oct 07 2021 at 13:25):
There's a default narrative generator for CapabilityStatement that exposes most stuff. There's also a transform I use here that I think creates slightly better narrative.
Eric Haas (Oct 07 2021 at 16:33):
https://github.com/Healthedata1/MyBinder/blob/master/CapStatement/Narrative_generator.ipynb will take a capability statement and create a pretty narrative. also available as notebook file: https://hub.gke2.mybinder.org/user/healthedata1-mybinder-4wcdenjg/lab/tree/CapStatement
still very much alpha and not merged with Cory's features.
Corey Spears (Oct 22 2021 at 02:28):
I finally had the opportunity to put my additions up in a github repo: https://github.com/cspears-mitre/CapStatement
There are 2 scripts. One to take an xslx input to create a CapabilityStatement with Narrative. The other to take in a json CapabilityStatement input and creates a new CapabilityStatement file with the Narrative included.
It includes the r4models necessary to support the element extensions used to include capabilitystatement-expectation extension.
It is still a quick and dirty tool. Hope to polish it more in the future and possibly merge with other tooling so there is only one place one has to go to get the latest and greatest (and we don't have unnecessarily divergent versions).
Jose Costa Teixeira (Oct 23 2021 at 12:20):
In CapStatement / CapStatement2, can we consideradding the publisher as a reference(organization)?
Jose Costa Teixeira (Oct 23 2021 at 12:22):
Also, I see that implementation.custodian says "Organization that manages the data" - assuming that who manages the data is not necessarily the same as who manages the server, can we make that clearer?
Corey Spears (Oct 24 2021 at 04:41):
Zulip is a great place to discuss. When you are ready, would you mind entering a Jira Ticket on FHIR Core if you would like to see these changes in the standard?
Jose Costa Teixeira (Oct 24 2021 at 10:28):
I will. I don't know if those are good ideas or if anyone else has similar or opposing requirements
Last updated: Apr 12 2022 at 19:14 UTC
