ITI-68: incompatibility with the FHIR Binary read operation

[qligier]

Section Number 2:3.68.4.1.2 Message Semantics

Issue
At the European Connectathon, we have seen multiple vendors using a regular FHIR Binary read URL as ITI-68 endpoint (e.g. DocumentReference.content.attachment.url = http://example.com/fhir/Binary/a54ef236-7e13-48be-951c-1ab7a6a2611f).

This seems to be non-compliant with the ITI-68 specifications in some edge cases:

• If the stored document is anything but a FHIR resource, and the ITI-68 request contains Accept: application/fhir+xml (or JSON)
  MHD should fail with a 406 Not Acceptable, or convert the document into a FHIR resource (document Bundle)
  FHIR should return the FHIR Binary.
• If the stored document is a FHIR resource, and the ITI-68 request contains Accept: application/fhir+xml (or JSON)
  MHD should return the document content (a FHIR resource).
  FHIR should return the FHIR Binary.

One might argue that transforming the stored document into a FHIR Binary is allowed by 2:3.68.4.1.2, so the first example is compliant. But the second one definitively isn't.

Is that incompatibility between both specifications already known?

Proposed Change
If it is a deliberate choice, could an explicit warning be added to the ITI-68 specification to inform vendors the FHIR Binary read is not suitable as ITI-68 endpoint?
If it is not a deliberate choice, should we discuss whether ITI-68 specifications should be updated to match the FHIR Binary read operation? The main argument in favour that I can think of is the simplicity of implementation (and unification of specifications).

Priority:
Medium

@oliveregger FYI

[JohnMoehrke]

The Document Responder is completely empowered to use whatever URL format they want. The Document Consumer must not expect any specific URL format, they must just do a GET. The Document Responder can use a URL format that appears to look like a Binary endpoint, it is their choice. The Document Responder can invent their own URL encoding, including using url parameters.

Note in MHDS, where the Document Registry is persisting the documents, these URLs will be Binary endpoints.

see https://profiles.ihe.net/ITI/MHD/ITI-67.html#236742211-document-location

This does setup the situation you describe, and that situation is fully expected. If the Document Consumer really does put FHIR in the accept header higher up than the mime-type of the document, then they ARE ASKING for a FHIR encoding as higher priority, and thus getting a FHIR Binary should be expected.

This is explained - https://profiles.ihe.net/ITI/MHD/ITI-68.html#2368412-message-semantics

Meaning that the Document Consumer must understand what they have placed into the http accept header, as it could change the mime-type of the content returned.

I speak to the benefits of using http negotiate on the ITI-68 in my tutorials.

[JohnMoehrke]

committee review:
It is unclear what problem you are trying to describe. As I have commented above, ITI-68 has few requirements. ITI-68 is compatible with a FHIR Binary endpoint, but ITI-68 does not require a FHIR Binary endpoint. The folder /Binary/ is not exclusive to FHIR Binary definition. The http Accept header allows the server to return the content they have.

Please explain the exact problem. Specifically what has happened that has caused what bad behavior. What text in the MHD specification is a problem, and how would you recommend it be changed.

[qligier]

We have seen different implementations of Document Responders and there was disagreement what the expected response should be for ITI-68 when using an Accept Header with application/fhir+json / application/fhir+xml.

Let’s look at examples to illustrate the issue. Let’s take two different implementations, one based on a FHIR server with Binary endpoint for the files and one custom implementation just using a storage.

1. Example; If the stored document is a FHIR resource (e.g. Bundle in this example) in XML representation, we get the following result

MIME-type of the stored document: application/fhir+xml	FHIR implementation GET /Binary/{id}	Custom implementation GET /custom/path
No Accept header	The XML Bundle is returned	The XML Bundle is returned
Accept = application/fhir+xml	The XML Binary resource containing the Bundle is returned link	The XML Bundle is returned link
Accept = application/fhir+json	The JSON Binary resource containing the Bundle is returned link	Either 406 not Acceptable, or the JSON Bundle is returned link

The issue lies in the difference of responses when using the Accept: application/fhir+xml or Accept: application/fhir+json header for a stored document with a content-type of application/fhir+xml or application/fhir+json : the returned content is dependent on the Document Responder implementation, if it uses the FHIR Binary you get a FHIR Binary Resource back, otherwise you get a FHIR Bundle resource back. This is a problem for the Document Consumer as we have seen it at the connectathon. The Document Consumer has no way of knowing the behaviour and the Document Responder cannot declare which variation it supports, and we have seen both implementations in Document Responders and the consumer struggling what to expect. We also saw a Document Consumer who always used the Accept header with application/fhir+json to specifically request the Binary resource for all documents.

2. Example: If the stored document is a PDF, we get the following result:

MIME-type of the stored document: application/pdf	FHIR implementation GET /Binary/{id}	Custom implementation GET /custom/path
No Accept header	The PDF is returned	The PDF is returned
Accept = application/pdf	The PDF is returned	The PDF is returned
Accept = application/fhir+json	The JSON Binary resource containing the PDF is returned link	Either 406 Not Acceptable, or a JSON resource is returned Link

This is also a similar issue, as most of the Document Responders which do not provide the Document via a FHIR API return a 406, which is correct, but the Document Consumer does not know which behaviour it has to expect.

From the discussion FHIR Binary endpoint is allowed in ITI-68, we suggest adding a sentence such as:

Note: If the document is encoded as a FHIR resource (application/fhir+xml or application/fhir+json), and the Document Consumer includes in the request an Accept header with the original MIME type, then the Document Responder may return a FHIR Binary resource containing the original document content.

In addition, the sentence:

For example, indicating application/fhir+json could result in the response from the Document Responder being a json FHIR Bundle of type document with all the content encoded as FHIR resources.

will never be realisable if the Document Responder is using a Binary endpoint, we suggest removing this sentence, or changing it for another example.

[JohnMoehrke]

From the description of the problem, I don't see how your recommended additional sentence helps.

The problem statement indicates that there are clients that are not following the http specification. If they were to simply follow that specification they would understand that 406 is a legitimate error code for when the server can't satisfy the accept header limits.

ITI-68 is purely http. It is not constrained to FHIR Binary. The references section should be changed to state this, and not mention FHIR. I am not sure what is confusing people into thinking that ITI-68 is describing FHIR Binary, it is not. It is simply describing http GET.

the FHIR Attachment.url is also just a url, it is not constrained to FHIR Binary.

Emphasizing these points seem more useful points?

[JohnMoehrke]

Note that if the client indicates in accept that they understand FHIR, then they are indicating that they understand FHIR. Thus they would be able to distinguish these various responses by looking at the response mime-type to understand it as a FHIR response vs something else. Emphasis that this is simply http

[oliveregger]

The problem statement indicates that we have different behaviour in ITI-65 response if the stored document has a mime-type from FHIR depending on the implementation of the Document Responderwhere a) it is a plain url or b) is also to be allowed to point to a FHIR Binary endpoint. This has nothing to do with the client / 406 or correct not following the http specification. Why should we not put on a note that this situation can occur when we see the different behaviours in implementations?
@JohnMoehrke do you disagree that this different behaviour exists as it is pointed out?

Note: If the document is encoded as a FHIR resource (application/fhir+xml or application/fhir+json), and the Document Consumer includes in the request an Accept header with the original MIME type, then the Document Responder may return a FHIR Binary resource containing the original document content.

[JohnMoehrke]

I don't dispute the details explained. But these results are consistent with http get. Therefore I don't see it as a problem to have these differences. I have offered my recommended changes that stress that ITI-68 is purely http. I don't mind at all helping our readers understand. I was merely pointing out that the recommended remedy didn't seem to me to stress the importance of the actual standard required, that is http, and not FHIR. I do not think that ITI-68 should be emphasizing Binary, as it is NOT Binary.

[oliveregger]

the results are not consistent with http get. I put out two exactly http get calls with an accept header (which is allowed by http get), but depending on the document responder implementation I get a structural complete different result, this is not interoperability ...

we dont need to emphasize ITI-68 with Binary, but we should be able to detect it as a consumer if it is used in iti-68. Why is the capabilitystatement of the MHD Document Responder indicating Binary READ? would that be a way to point out the differentiation?

[JohnMoehrke]

what are the deviations from http get that you have seen? Those are what we should focus on.

The capabilityStatement likely should be corrected. That one is not wrong for a system that did choose to implement ITI-68 with Binary endpoint. But ITI-68 does not require Binary endpoint.

[qligier]

The issue is that the ITI-68 specification does not detail enough what will be returned by the Document Responder to the Document Consumer when using an Accept header. Anything could be returned. Even when the consumer asks for a document of the same MIME type as the original content, the responder could return anything, as long as the MIME type is correct. That is valid according to the HTTP specifications, but not acceptable for an IHE transaction because it is simply not interoperable.
If the consumer has to ask the responder for implementation details just to be able to retrieve a document, that is not interoperability, that's a proprietary API.

[JohnMoehrke]

It is an http GET of the URL provided in the attachment.url.

if the client indicates in accept headers that they understand FHIR, then I would expect that the client understands FHIR. Thus I would expect the client understands how to look at a http body to determine that the response is FHIR, and then look at the response body to determine the FHIR Resource.

if the client indicates in he accept headers that they understand the mime-type indicated in attachment.contentType, then I would expect that content to be returned.

What is not clear?

I am not against being more specific in ITI-68; but I will not accept that ITI-68 is a FHIR Binary endpoint. That is too limiting to both the server and client. http negotiation is sufficient.

[oliveregger]

if the client indicates in he accept headers that they understand the mime-type indicated in attachment.contentType, then I would expect that content to be returned.

What is not clear?

That we have undetermined behaviour in the response as we indicate in the example 1. HTTP negotiation is completely the same for the client but the response is different.

I am not against being more specific in ITI-68; but I will not accept that ITI-68 is a FHIR Binary endpoint. That is too limiting to both the server and client. http negotiation is sufficient.

How are you meaning this? Neither @qligier nor myself are advocating that it SHALL be FHIR Binary endpoint. But is your sentence meant that it SHALLT NOT be a FHIR Binary endpoint?

[JohnMoehrke]

please put forward a proposed change.