2.1.27.5 DomainResource Resource

2.1.27.5.1 Scope and Usage

A domain resource is a resource that:

• has a human-readable XHTML representation of the content of the resource (see Human Narrative in resources)
• can contain additional related resources inside the resource (see Using Contained Resources below and Contained Resources)
• can have additional extensions and modifierExtensions as well as the defined data (See Extensibility)

As an abstract resource, this resource is never created directly; instead, one of its descendant resources (see List of Resources) is created.

2.1.27.5.2 Boundaries and Relationships

This resource extends the base Resource. All of the listed Resources except Bundle, Parameters and Binary extend this resource.

2.1.27.5.4 Using Contained Resources

The 'contained' mechanism is not permitted as a means of reducing server calls. I.e., It is not allowed to package a set of resources as one base resource and a set of contained resources to allow multiple creates or updates to happen in a single transaction, nor is it permitted to use 'contained' as a means of retrieving multiple resources in a single 'read'.

'contained' is only for use when there is a need to reference another resource, but the target resource does not have any independence from the referencing resource. Most commonly, this occurs when not enough information is known to allow uniquely identifying the target resource. For example, if a surgeon is known only as "Dr. Smith" (no full name, no license number, etc.), then there would be no way of determining which of the candidate "Dr. Smith" practitioners was being referenced. In that situation, it would be reasonable for the Procedure to have a 'contained' reference to the Practitioner.

In other cases, there might be enough information to construct an independent resource, but system behavior does not recognize/permit an independent identity. As an example, a prescriber might create a prescription for a custom compound. However, rather than registering the compound as a new 'Medication' instance (that could be pointed to by many prescriptions/dispenses), the system treats the compound recipe as 'part' of the prescription - it can only be edited/modified in the context of that one prescription and cannot be queried or manipulated independently. If the prescription were deleted, the Medication would be deleted as well. This would be an appropriate use of 'contained'.

A key consideration with respect to 'contained' resources is that if a resource is sent to a server as 'contained', then it is expected to remain 'contained' (at least until a formal update is received that removes the 'contained' resource and perhaps replaces it with a reference to a stand-alone resource due to additional information now being available).

For implementations concerned about minimizing the number of service calls, FHIR provides a number of options:

• When sending creates or updates, leverage the transaction feature to create/update multiple (interrelated) resources at once
• When querying for data, make use of _include and _revinclude to return additional resources that are relevant as part of the query
• Operations can be defined that allow manipulation or retrieval of multiple resources as part of a single action.
• The document and messaging paradigms also support the simultaneous transport of multiple resources.

REST can be somewhat heavy in terms of the number of service calls needed to manipulate all desired resources. This is part of the cost associated with the flexibility that allows a single RESTful interface to support a wide range of use-cases.

2.1.27.5.4.1 Using additional resources in DomainResource.contained

Contained resources may be either be one of the 160 resources defined in this specification, or an additional resource.

In JSON, this looks like:

{
  "resourceType" : "Basic",
  "contained" : [{
    "resourceType" : "ViewDefinition",
    "resourceDefinition" : "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition|2.0.0-pre",
    "id": "a-valid-id",
    // etc
  }]
}

In XML, this looks like:

<Basic xmlns="http://hl7.org/fhir">
  <contained> 
    <ViewDefinition xmlns="http://hl7.org/fhir" 
      resourceDefinition="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/ViewDefinition|2.0.0-pre">
      
      // etc
    <ViewDefinition>
  </contained> 
</Bundle> 

See general note to balloters about Additional resources

2.1.27.5.5 Searching Extensions

The FHIR specification does not define SearchParameters for most of the standard extensions we publish and obviously cannot define SearchParameters for extensions developed by implementers outside the core FHIR specification. However, implementers are free to define their own SearchParameters for any extensions they make use of and servers are free to support SearchParameters above and beyond those published as part of the FHIR core specification. There are no formal naming rules for extension-based search parameters. Authors SHOULD name the search parameters in such a way that the linkage between the extension name and the search parameter is obvious.

The expression for the search parameter would typically end with extension('http://yourextensionurlhere').value. The expression would also need to provide a path to the extension, including handling situations where an extension appears on multiple paths if necessary. Additional constraints could also be added if necessary (e.g. .exists(), =true, etc.)