FHIR Chat · CapabilitiesStatement2 support

I attended the Q2 discussion today about the CapabilityStatement and CapabilityStatement2. The discussion between @Ewout Kramer , @Grahame Grieve and @Josh Mandel was very complex .

I am struggling to understand why we would need a CapabilityStatement with so many features? Is there a usecase where a client application searches for a "capable" server at runtime? In order to be able to process and parse a CapabilityStatement, the software to process and parse it also becomes complex. Is a client application going to "query" using the "features" at run time using code value pairs? Implementing this type of parsing of CS2 would be very difficult due to the number of features that may need to be supported and the
ValueSets of the code/value pairs that would need to be maintained by the client application.

Any clarification on the need and usecase would be greatly appreciated,.

Thanks,

Joel and @Alex Goel

Josh Mandel (May 24 2021 at 19:32):

I generally agree with your question @Joel Francis. In many (most, I'd bet) cases "read the docs out of band" is a good enough alternative to in-band negotiation. And it can convey a ton of nuance that our carefully modeled features sometimes miss.

Josh Mandel (May 24 2021 at 19:35):

That said, we do have a lot of variability across server behaviors, and as we look at more flexible/dynamic ways of creating connections, I totally get why there's interest here.

Alex Goel (May 24 2021 at 19:49):

@Josh Mandel I am not sure what "flexible/dynamic ways of creating connections" necessarily means in this context, unless you are suggesting that a client application is expected to query for what features are available at runtime, which as @Joel Francis mentioned would be very difficult to implement in a production client application.

From our perspective the main time when the content from the CapabilityStatement would be leveraged is when a Service Level Agreement (SLA) and/or Data Sharing Agreement (DSA) is established. This SLA/DSA will likely specify what is contractually required to be shared between two entities. It is unlikely given the security and privacy constraints of healthcare that anyone would need to do this on the fly. Is our interpretation of the potential use case incorrect?

Joel Francis (May 24 2021 at 19:52):

Agreed. Honestly I do not see a situation where a production application queries features on the fly. I think the only time this would happen is at the Connectathon or during initial testing

Josh Mandel (May 24 2021 at 19:52):

I am not sure what "flexible/dynamic ways of creating connections" necessarily means in this context, unless you are suggesting that a client application is expected to query for what features are available at runtime, which as @Joel Francis mentioned would be very difficult to implement in a production client application.

Yeah, these are patterns that groups like "FAST" are looking at. There's significant complexity here, as you note.

Michele Mottini (May 24 2021 at 19:53):

Our (production) client queries feature on the fly. It checks for availability of search parameters to decide which query to generate

Josh Mandel (May 24 2021 at 19:54):

SLA/DSA will likely specify what is contractually required to be shared between two entities

I think you're describing a kind of offline or static use case for publishing and/or evaluating a CapabilityStatement, which is certainly fair game. Even in this context, knowing specific features (whether documented in prose, or in concrete tags/extensions/feature-json format) matters.

Alex Goel (May 24 2021 at 20:06):

@Michele Mottini
Given that the CS2 is brand new for FHIR R5, I assume that your production application dynamically generates search parameters (which is something I would expect a production app to do), and does not query for features. Is that correct? Does it search the CapabilityStatement for what REST parameters are accepted by the server?

@Josh Mandel In the registration use case for FAST, what is the purpose of the CapabilityStatement? What would it be used for? From the PSS, this appears to mostly be focused on registering authentication endpoints. It seems for this use case a client app would not need to dynamically process a CapabilityStatement, it would be known once the app was registered automatically. Am I missing something?

I agree that having these features documented, especially from a testing perspective in a CapabilityStatement is necessary and valuable, but where I do not understand when a client server would dynamically respond to what is in a CapabilityStatement.

I think a key point we want to emphasize is that we are asking when this would need to be done at runtime.

Josh Mandel (May 24 2021 at 20:10):

It seems for this use case a client app would not need to dynamically process a CapabilityStatement, it would be known once the app was registered automatically. Am I missing something?

I'm just saying that in the FAST pattern there's an expectation of more flexible config, where clients and servers might be introduced automatically and start interacting right away without developers "doing an integration" or reading a specific server's docs. I'm not the best person to weigh in on this; just trying to infer what I can about where folks are trying to take this work in the future.

Josh Mandel (May 24 2021 at 20:11):

I think a key point we want to emphasize is that we are asking when this would need to be done at runtime.

For any given use case, there may not be a need. Clearly we can imagine some use cases where there is a need; whether these are going to be important and achievable (from a pragmatic perspective) isn't totally clear; that's part of what we want to figure out through use case discussion and a connectathon track.

Michele Mottini (May 24 2021 at 20:15):

Does it search the CapabilityStatement for what REST parameters are accepted by the server?

Yes

Alex Goel (May 24 2021 at 22:11):

My main concern here is how complex this is becoming, before we can do the simple things at a wide scale. I agree that we need to innovate through discussion and testing, but we need clear problems to solve otherwise we're just adding complexity which could actively hurt how easy FHIR is to implement

Josh Mandel (May 24 2021 at 22:13):

I strongly agree!

Grahame Grieve (May 24 2021 at 23:02):

I think the primary initial application here is safety. There is very definitely a desire to right smart applications that are portable across applications, and that don't require redevelopment across servers.

Either the servers can be forced to be consistent, which is not possible even amongst ourselves, or we let the applications find out information about the servers, or at least, insist that some kinds of server behaviors be true

Grahame Grieve (May 24 2021 at 23:04):

Is there a usecase where a client application searches for a "capable" server at runtime? I

there is, but for me, the use cases are less ambitious, and more compelling

In order to be able to process and parse a CapabilityStatement, the software to process and parse it also becomes complex

The point is to avoid that. Make a list of features you need, ask the server if it supports them all. No processing needed.

Grahame Grieve (May 24 2021 at 23:05):

we need clear problems to solve otherwise we're just adding complexity which could actively hurt how easy FHIR is to implement

Well, there's a tension between narrowly defined fragile software that is easier to write, and where you do not want to have to deal with that complexity, and robust adaptable software where you have no choice but to engage with it. That's a trade-off that runs through all of what we do

Alex Goel (May 24 2021 at 23:18):

Grahame Grieve said:

In order to be able to process and parse a CapabilityStatement, the software to process and parse it also becomes complex

The point is to avoid that. Make a list of features you need, ask the server if it supports them all. No processing needed.

To this point, the CapabilityStatement would be retrieved during app development/testing to ensure that the correct data could be retrieved. It wouldn't necessarily be done at run time correct?
@Joel Francis please jump in

Joel Francis (May 24 2021 at 23:30):

Sharing my understanding......The whole SMART concept is to make apps that are substitutable and reuseable. The fact that their on FHIR and a particular version on FHIR meant that I can interchange without any redevelopment and simply have to sign a service level agreement .While signing the service level agreement I will make sure the FHIR server can provide that data otherwise my app would be useless. So based on that why would my app need to re-query the capabilities of the server???

Josh Mandel (May 25 2021 at 00:20):

It sounds like you may be expecting too much from FHIR; it's best to keep in mind that the specification defines a wide surface area and different servers implement different subsets and make different choices around optional features

Lloyd McKenzie (May 25 2021 at 01:08):

Some of the use-cases for FHIR involve developing clients where the developer will never read the documentation of the server - or even know what servers it will be connected to. That application will have to determine when pointed at an arbitrary server:
a) whether it is capable of safely operating at all; and
b) if it needs to alter what it does based on the server's limitations

And that's actually a desirable target state for much of the FHIR environment. We're trying, where we can, to reduce the amount of site-to-site negotiation and customization necessary for systems to operate. One of the primary purposes of CapabilityStatement is to allow that runtime negotiation.

The other purpose of CapabilityStatement is to make clear what a system does from a conformance perspective. The more implementation guides define variations in potential behavior, the greater the set of things a server may need to declare.

Alex Goel (May 25 2021 at 16:42):

From a safety perspective the CapabilityStatement makes sense, but we're wondering what is the necessity of CS2? It seems like this would be negotiated well in advance, even if the developers did not have an SLA to work of. It wouldn't be negotiated at run time.

Patient safety would also likely be negotiated in an SLA, since you wouldn't want to share any data with an entity you are allowed to share data with. Data should not be opened up to potential privacy breaches in this regard. We believe that if you're connecting to a FHIR server, in the majority of use cases (certainly 80%) you'd be connecting to a known FHIR server; one which you have an SLA and Data Sharing Agreement with.

Alex Goel (May 25 2021 at 16:45):

Josh Mandel said:

It sounds like you may be expecting too much from FHIR; it's best to keep in mind that the specification defines a wide surface area and different servers implement different subsets and make different choices around optional features

I don't think we're expecting too much from FHIR, I believe we're anticipating how real world implementations of FHIR will operate at a governance level. People will need to agree to use the same specifications, and profiles from FHIR, IHE, etc. to ensure what can be shared is interoperable. FHIR provides a data sharing model, not governance on how data can, should, and will be shared. It's still up to legal agreements to determine that

Josh Mandel (May 25 2021 at 16:53):

I was referring specifically to this assertion:

The fact that their on FHIR and a particular version on FHIR meant that I can interchange without any redevelopment and simply have to sign a service level agreement .

Joel Francis (May 25 2021 at 17:15):

Sorry for being vague, but what I meant to say is, a SMART app would need to know what it will retrieve (and what is available) from a FHIR server it is interacting with. What I meant by this was that assertion is that if during the SLA, if a SMART client knew that the server was not capable of providing data in a specific version of the FHIR model, not understood by both the server of the client, regardless of if it was FHIR or any other data exchange format, then it would be pointless to sign the service level agreement.

Michele Mottini (May 25 2021 at 17:17):

In most cases there is no SLA not any direct contact between the client developer and the server. This is the case for all patient apps in the US market

Alex Goel (May 25 2021 at 17:22):

@Michele Mottini so there's no legal agreement or business rules around what patient data is allowed to be exchanged?

Michele Mottini (May 25 2021 at 17:28):

Yes, there is no legal agreement between patient app developers and providers / payers hosting the FHIR APIs. Providers and payers have to make the API available and allow any app to connect.

Grahame Grieve (May 25 2021 at 17:29):

not an explicit one between developer and server, no. Now you might always ensure that this is the case - fine, you can. And if you do, then you won't value any reflection features we add, since this is all sorted out by engineers during contract negotiations.

but that's not how all exchanges will work, and we're added reflection features and feature negotiation to support other users

Alex Goel (May 25 2021 at 17:29):

Yes but there are still rules around what data is to be made available, and in what format, and there is still negotiation of those rules. I assume you're referring to information blocking @Michele Mottini

Paul Church (May 25 2021 at 17:29):

+1 to Michele - there are a lot of providers (and payors) in the US, and a lot of patient apps. Most of them have no contractual relationship to each other. Capability statements are very useful here, although I'm skeptical that many of the smaller apps are truly sophisticated enough to adapt their behaviour according to the server's capabilities.

I would consider the use case where a data holder and a data consumer have an SLA and a data sharing agreement as distinct from that model.

Alex Goel (May 25 2021 at 17:31):

Paul Church said:

I'm skeptical that many of the smaller apps are truly sophisticated enough to adapt their behaviour according to the server's capabilities.

Agreed

Grahame Grieve (May 25 2021 at 17:31):

I'm skeptical that many of the smaller apps are truly sophisticated enough to adapt

It's not first about adapt. First, it's check, and we all have a vested interest in that

Paul Church (May 25 2021 at 17:32):

Agreed, I think the first bar to clear is "don't talk to the server if it doesn't have enough capabilities for your expectations"

Michele Mottini (May 25 2021 at 17:32):

@Alex Goel Yes, there are rules about the minimum set of resources providers and payers have to make available, but beyond that there are a lot of variations, and as I wrote our app definitely use the CapabilityStatement at run time to detect these variations and act accordingly

Alex Goel (May 25 2021 at 17:33):

Ok, but if the use case is check if the capability is there, that's different than dynamically responding to the server's capabilities at run time - which if you return to the beginning of this conversation, where @Joel Francis and I had an issue

Paul Church (May 25 2021 at 17:33):

CareEvolution is a good example of the next level up, adapt your approach according to the capabilities

Grahame Grieve (May 25 2021 at 17:34):

where @Joel Francis and I had an issue

your issue has always appeared to be "I don't want to do this, so no one else can reasonably want to"

Alex Goel (May 25 2021 at 17:35):

If you set the system to favour these level'd up apps only, you're creating an uneven playing field for all of the small apps, and preventing those small apps from being innovative, our issue is that, dynamically responding to CapabilityStatements is an unfair expectations for all interactions

Grahame Grieve (May 25 2021 at 17:38):

OK. It's reasonable concern, and I'm happy to make sure that the final outcome doesn't require servers and clients to adapt to feature availability, or even perform feature negotiation, or have dynamically adjusting capability statements, though IGs will be able to require those things

Joel Francis (May 25 2021 at 17:41):