Proper use of 'contained' property

I was experimenting with the HAPI-FHIR server at, and noticed that in a response to a MedicationOrder inquiry (, it had a “Patient” resource in the collection of resources in the ‘contained’ property. Separately, within the MedicationOrder, the “patient” property made a reference to this contained entity.

My interpretation of the ‘contained’ property is that it should only be used for resources that are wholly contained by the parent, and really aren’t visible outside of the context of that resource. In this example, that was true, as an inquiry against a top-level Patient resource at HAPI-FHIR did not return the patient associated with this MedicationOrder.

Is my interpretation correct? If so, if a top-level Patient resource did exist, then I assume there would not be a Patient resource in the ‘contained’ property, and the ‘patient’ property would contain a reference like:
“patient” : {
“reference”: “”,
“display”: “Anna J Johnsen”

rather than:
“patient”: {
“reference”: “#16622”,
“display”: “Anna J Johnsen”

Correct. Contained resources are intended for circumstances where a resource doesn’t have enough information to stand alone. In the case of a MedicationOrder with a Patient, that would be exceptionally rare. However, in some use-cases such as anonymized reporting of prescriptions (e.g. Prescribed drug x to a 35-year-old female), it might make sense. Unfortunately, there’s a temptation by implementers who are new to FHIR to use it as a quick-and-dirty alternative to making separate REST calls or using transaction, operations or messaging to submit multiple records to a server. A key question to answer is “are you comfortable with the idea that the contained resource would always be contained?” If your expectation is that the server would ‘uncontain’ the resource, then you shouldn’t be using contained in the first place . . .