R4 Ballot #1 (Mixed Normative/Trial use)

This page is part of the FHIR Specification (v3.3.0: R4 Ballot 2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

2.33 Resource Binary - Content

FHIR Infrastructure

Work Group

Maturity Level: 5

Normative

Compartments: Not linked to any defined compartments

Normative Candidate Note: This page is candidate normative content for R4 in the Infrastructure Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

A binary resource can contain any content, whether text, image, pdf, zip archive, etc.

2.33.1 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:

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 - XDS)

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 or JSON, 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).

2.33.2 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.

This resource is referenced by EntryDefinition and ImplementationGuide

Structure

Name	Flags	Card.	Type	Description & Constraints
Binary	Σ N		Resource	Pure binary content defined by a format other than FHIR Elements defined in Ancestors: id, meta, implicitRules, language
contentType	Σ	1..1	code	MimeType of the binary content MimeType (Required)
securityContext	Σ	0..1	Reference(Any)	Access Control Management
content	Σ	1..1	base64Binary	The actual content
Documentation for this format

UML Diagram (Legend)

XML Template

<Binary xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <contentType value="[code]"/><!-- 1..1 MimeType of the binary content  -->
 <securityContext><!-- 0..1 Reference(Any) Access Control Management --></securityContext>
 <content value="[base64Binary]"/><!-- 1..1 The actual content -->
</Binary>

JSON Template

{
  "resourceType" : "Binary",
  // from Resource: id, meta, implicitRules, and language
  "contentType" : "<code>", // R!  MimeType of the binary content 
  "securityContext" : { Reference(Any) }, // Access Control Management
  "content" : "<base64Binary>" // R!  The actual content
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .


[ a fhir:Binary;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  fhir:Binary.contentType [ code ]; # 1..1 MimeType of the binary content
  fhir:Binary.securityContext [ Reference(Any) ]; # 0..1 Access Control Management
  fhir:Binary.content [ base64Binary ]; # 1..1 The actual content
]

Changes since R3

No Changes

Binary

See the Full Difference for further information

This analysis is available as XML or JSON.

See R2 <--> R3 Conversion Maps (status = 2 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.). Note: these have note yet been updated to be R3 to R4

Structure

Name	Flags	Card.	Type	Description & Constraints
Binary	Σ N		Resource	Pure binary content defined by a format other than FHIR Elements defined in Ancestors: id, meta, implicitRules, language
contentType	Σ	1..1	code	MimeType of the binary content MimeType (Required)
securityContext	Σ	0..1	Reference(Any)	Access Control Management
content	Σ	1..1	base64Binary	The actual content
Documentation for this format

UML Diagram (Legend)

XML Template

<Binary xmlns="http://hl7.org/fhir"> 
 <!-- from Resource: id, meta, implicitRules, and language -->
 <contentType value="[code]"/><!-- 1..1 MimeType of the binary content  -->
 <securityContext><!-- 0..1 Reference(Any) Access Control Management --></securityContext>
 <content value="[base64Binary]"/><!-- 1..1 The actual content -->
</Binary>

JSON Template

{
  "resourceType" : "Binary",
  // from Resource: id, meta, implicitRules, and language
  "contentType" : "<code>", // R!  MimeType of the binary content 
  "securityContext" : { Reference(Any) }, // Access Control Management
  "content" : "<base64Binary>" // R!  The actual content
}

Turtle Template

@prefix fhir: <http://hl7.org/fhir/> .


[ a fhir:Binary;
  fhir:nodeRole fhir:treeRoot; # if this is the parser root

  # from Resource: .id, .meta, .implicitRules, and .language
  fhir:Binary.contentType [ code ]; # 1..1 MimeType of the binary content
  fhir:Binary.securityContext [ Reference(Any) ]; # 0..1 Access Control Management
  fhir:Binary.content [ base64Binary ]; # 1..1 The actual content
]

Changes since DSTU2

No Changes

Binary

See the Full Difference for further information

This analysis is available as XML or JSON.

See R2 <--> R3 Conversion Maps (status = 2 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.). Note: these have note yet been updated to be R3 to R4

Alternate definitions: Master Definition XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) + see the extensions & the dependency analysis

2.33.3.1 Terminology Bindings

Path	Definition	Type	Reference
Binary.contentType	The mime type of an attachment. Any valid mime type is allowed.	Required	BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049)

Path

Definition

Type

Reference

Binary.contentType

The mime type of an attachment. Any valid mime type is allowed.

Required

BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049)

2.33.3.2 Serving Binary Resources using the RESTful API

Binary resources behave slightly differently to all other resources on the RESTful API. Specifically, when a read request is made for the binary resource that doesn't explicitly specify the FHIR content types "application/fhir+xml" or "application/fhir+json", then the content should be returned using the content type stated in the resource. e.g. if the content type in the resource is "application/pdf", then the content should be returned as a PDF directly.

Note that due to the way the web infrastructure works, it is not possible to make blanket rules about the relationship between the "Accept" field in the HTTP request, and the return type, which is why there is no hard rule about this. However, the intent is that unless specifically requested, the FHIR XML/JSON representation is not returned.

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:

Binary.meta.lastUpdated: Last-Modified
Binary.meta.versionId: ETag header
Binary.contentType: Content-Type
Binary.securityContext: X-Security-Context - this is a FHIR specific extension, primarily intended to allow the security context for a Binary resource to be specified when it is posted in native form

When a binary is written to the server (create/update - POST or PUT), the data is accepted as is and treated as the binary content of a Binary, including when the content type is "application/fhir+xml" or "application/fhir+json", except for the special case where the content is actually a Binary resource.

Note that when client requests a binary resource using a generic mime type (application/xml, text/xml, or application/json), the server SHOULD return the content directly if the content-type format matches the requested mime type (e.g. if the Accept header is appplication/json, and the contentType is vnd.xacml+json). However, servers might not always be able to interpret mime types correctly, and clients SHOULD be prepared to receive either format.

Note that the _summary parameter does not apply when the mime type is not one of the standard FHIR content types.

2.33.3.3 Security Considerations

Binary resources are not constrained, 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.

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.

2.33.3.4 Search

This specification does not support searching on Binary resources.