Existing Wording: $docref

Typically, DocumentReference resources are used with document indexing systems, such as IHE XDS. However, document references may also may be created "on-the-fly" in response to a Document Query request. In other words there MAY NOT be pre-existing index of references to a patient's documents at the FHIR endpoint. This results in an empty bundle being returned when searching using a normal FHIR Query. Therefore, the $docref operation has been defined to both create and fetch patient DocumentReference Resources.

Comment:

It is very confusing the intention of the $docref operation. It seems to be a duplicate of the more simple RESTful query. The given text seems to indicate that it would be impossible to "create and fetch" during a RESTful query. This is not specifically true except in an architecture that has not-otherwise-specified ways. If there is a special reason for a client to choose to use $docref vs using query parameters, then this must be explained. If there is a special reason why a server would want $docref to be supported, then this must be explained. Without these explaination then $docref should be removed from the specification as leaving it into the US-Core leads to interoperability problems as it provides two similar functionality for no defined benefit or difference.

I suspect the intent of $docref is good. It is just not well enough explained. I understand that as an operation the $docref would be more easy to intercept/orchistrate to enable dynamic (on-demand, or delayed-assembly) type documentReference entries). If this is the sole motiviation, then this needs to be more clearly said. If this done, then there must be some further mitigation of why a client would use $docref vs RESTful query; especially as this profile is orchistrated such as in clinical-note.

Further note, this $docref is NOT compliant with IHE-MHD profile. IHE-MHD profile has not received comments asking for an operation.

Summary:

Further explan the docref operation or remove