Resource type: binary

Description

A resource that represents the data of a single raw artifact as digital content accessible in its native format. A Binary resource can contain any content, whether text, image, pdf, zip archive, etc.

Elements

PathShortDefinitionComments
Pure binary content defined by a format other than FHIRA resource that represents the data of a single raw artifact as digital content accessible in its native format. A Binary resource can contain any content, whether text, image, pdf, zip archive, etc.Typically, Binary resources are used for handling content such as: * CDA Documents (i.e. with XDS) * PDF Documents * Images (the Media resource is preferred for handling images, but not possible when the content is already binary - e.g. XDS).
contentTypeMimeType of the binary contentMimeType of the binary content represented as a standard MimeType (BCP 13).
securityContextIdentifies another resource to use as proxy when enforcing access controlThis element identifies another resource that can be used as a proxy of the security sensitivity to use when deciding and enforcing access control rules for the Binary resource. Given that the Binary resource contains very few elements that can be used to determine the sensitivity of the data and relationships to individuals, the referenced resource stands in as a proxy equivalent for this purpose. This referenced resource may be related to the Binary (e.g. Media, DocumentReference), or may be some non-related Resource purely as a security proxy. E.g. to identify that the binary resource relates to a patient, and access should only be granted to applications that have access to the patient.Very often, a server will also know of a resource that references the binary, and can automatically apply the appropriate access rules based on that reference. However, there are some circumstances where this is not appropriate, e.g. the binary is uploaded directly to the server without any linking resource, the binary is referred to from multiple different resources, and/or the binary is content such as an application logo that has less protection than any of the resources that reference it.
dataThe actual contentThe actual content, base64 encoded.If the content type is itself base64 encoding, then this will be base64 encoded twice - what is created by un-base64ing the content must be the specified content type.

Scope and Usage

There are situations where it is useful or required to handle pure binary content using the same framework as other resources. Typically, this is when the binary content is referred to from other FHIR Resources. Using the same framework means that the existing servers, security arrangements, code libraries, etc. can handle additional related content. Typically, Binary resources are used for handling content such as:

A binary resource can contain any content, whether text, image, pdf, zip archive, etc. These resources are served in their native form on the rest interface, but can also be represented in XML, JSON, or other formats, such as when including these resources in a Bundle (used when it is convenient to include these in the response directly rather than leaving them by reference).

Boundaries and Relationships

When a FHIR server finds it convenient to manage the content within the same overall REST framework as the other resources, the Binary resource is generally used as the target in the Attachment data type to reference content via the .url element, such as in the DocumentReference and Media resources. Consequently, the Binary resource can be a target wherever the Attachment data type is used such as in the DocumentReference resource.

The DocumentReference and Media resources allow conveying binary content (via attachment) or pointing to one (as a Binary or non-FHIR URI) along with the metadata around that resource, and as such are searchable. Binary resources do not support 'search'.

While CDA and PDF documents are conveyed as Binary (because they cannot be expressed natively in FHIR), FHIR Documents do not need to be similarly encoded and can be sent natively in FHIR using Bundle. However, in some situations FHIR Documents may be sent as a Binary if there is a need to treat them the same as other types of documents or binary files.

The Binary resource does not convey context of the file. If the context (information such as author, procedure, technique, etc.) should be conveyed, Media or DocumentReference resources are appropriate. The Binary resource may be used to convey actual binary file content conveyed by those resources.

The Media resource is preferred for handling images, but this is not possible when the content is already binary (e.g. in some uses of IHE XDS).

Content Optionality

Binary.data is optional because it is excluded when a summary view of the Binary resource is requested (this can be useful when the binary resource is part of a wider request e.g. a search _include).

Otherwise, the data is not optional; a binary resource without any specified content it not useful.

Serving Binary Resources using the RESTful API

Binary resources behave slightly differently from all other resources on the RESTful API:

Note that in the native binary representation, the normal resource metadata is not available directly, though some of it is replicated in the HTTP response headers. Specifically, the following elements of the resource have matching HTTP Headers:

Security Considerations

Binary resources are not constrained to any list of safe content types (content types without active elements such as scripting or executable code), and therefore can be of any content type and encoding. Therefore, extra care needs to be taken to validate the content of the Binary resource against malicious or malformed content. For more details see Security of Narrative, since the security issues are similar.

Very often, the content of a Binary resource is sensitive, and the server should apply appropriate access control to the content. When the server itself generates the content, it implicitly knows what access control to apply. When the client provides the binary to the server itself, it uses the securityContext element (or the matching X-Security-Context HTTP header) to inform the server that the Binary resource should be treated as if it was the other resource. Typically, the other resource is a DocumentReference or similar resource that refers directly to the Binary resource, but that is not mandatory.

Read

This specification makes no rules concerning advanced read functionality for the Binary resource, such as:

Servers are free to support these features, but they are not required.

Search

This specification does not support searching on Binary resources.

Patch

The semantics of a PATCH operation on a Binary resource are not currently specified.

Search Parameters

Extension Definitions

These are extension definitions for this resource defined by the spec