R4 Ballot #1 (Mixed Normative/Trial use) R5 Final QA

This page is part of the FHIR Specification (v3.3.0: R4 Ballot 2). (v5.0.0-draft-final: Final QA Preview for R5 - see ballot notes ). 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 2.3 Resource Binary - Content

FHIR Infrastructure icon Work Group Maturity Level : 5 N   Normative (from v4.0.0) Security Category : Not Classified Compartments : Not linked to any defined compartments
Normative Candidate Note: This page is candidate normative

A resource that represents the data of a single raw artifact as digital content for R4 accessible in the Infrastructure Package . Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made. its native format. A binary Binary resource can contain any content, whether text, image, pdf, zip archive, etc.

2.33.1 2.3.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 libraries, etc. can handle additional related content. Typically, Binary resources are used for handling content such as:

  • CDA icon 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 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).

2.33.2 2.3.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 The DocumentReference resource allows 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 referenced 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.) is needed it should be conveyed in a DocumentReference resource. The Binary resource may be used to convey actual binary file content conveyed by EntryDefinition the DocumentReference resource.

See some uses of Binary and DocumentReferece in the IHE XDS icon Implementation Guide.

2.3.3 References to this Resource

2.33.3 2.3.4 Resource Content

Structure

Σ
Name Flags Card. Type Description & Constraints doco
. . 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 Binding: Mime Types ( Required )
. . . securityContext Σ 0..1 Reference ( Any ) Access Control Management Identifies another resource to use as proxy when enforcing access control
. . content . data 1..1 0..1 base64Binary The actual content

doco Documentation for this format icon

See the Extensions for this resource

XML Template 

<

<Binary xmlns="http://hl7.org/fhir"> doco

 <!-- from Resource: id, meta, implicitRules, and language -->
 <
 <</securityContext>
 <

 <contentType value="[code]"/><!-- 1..1 MimeType of the binary content -->
 <securityContext><!-- 0..1 Reference(Any) Identifies another resource to use as proxy when enforcing access control --></securityContext>
 <data value="[base64Binary]"/><!-- 0..1 The actual content -->

</Binary>

Turtle Template 

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


[ a fhir:;

[ a fhir:Binary;

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

  # from Resource: .id, .meta, .implicitRules, and .language
  fhir:
  fhir:
  fhir:

  fhir:contentType [ code ] ; # 1..1 MimeType of the binary content
  fhir:securityContext [ Reference(Any) ] ; # 0..1 Identifies another resource to use as proxy when enforcing access control
  fhir:data [ base64Binary ] ; # 0..1 The actual content

]

Changes since R3 R4

Binary
  • No Changes

See the Full Difference for further information

This analysis is available as XML or JSON .

See R2 <--> R3 <--> R4 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 valid.)

Structure

Σ
Name Flags Card. Type Description & Constraints doco
. . 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 Binding: Mime Types ( Required )
. . . securityContext Σ 0..1 Reference ( Any ) Access Control Management Identifies another resource to use as proxy when enforcing access control
. . content . data 1..1 0..1 base64Binary The actual content

doco Documentation for this format icon

See the Extensions for this resource

XML Template 

<

<Binary xmlns="http://hl7.org/fhir"> doco

 <!-- from Resource: id, meta, implicitRules, and language -->
 <
 <</securityContext>
 <

 <contentType value="[code]"/><!-- 1..1 MimeType of the binary content -->
 <securityContext><!-- 0..1 Reference(Any) Identifies another resource to use as proxy when enforcing access control --></securityContext>
 <data value="[base64Binary]"/><!-- 0..1 The actual content -->

</Binary>

Turtle Template 

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


[ a fhir:;

[ a fhir:Binary;

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

  # from Resource: .id, .meta, .implicitRules, and .language
  fhir:
  fhir:
  fhir:

  fhir:contentType [ code ] ; # 1..1 MimeType of the binary content
  fhir:securityContext [ Reference(Any) ] ; # 0..1 Identifies another resource to use as proxy when enforcing access control
  fhir:data [ base64Binary ] ; # 0..1 The actual content

]

Changes since DSTU2 Release 4

Binary
  • No Changes

See the Full Difference for further information

This analysis is available as XML or JSON .

See R2 <--> R3 <--> R4 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 valid.)

 

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

2.33.3.1 2.3.4.1 Terminology Bindings

Path Definition ValueSet Type Reference Documentation
Binary.contentType The mime type of an attachment. Any MimeTypes (a valid mime type is allowed. code from urn:ietf:bcp:13 ) Required BCP 13 (RFCs 2045, 2046, 2047, 4288, 4289 and 2049)

This value set includes all possible codes from BCP-13 (see http://tools.ietf.org/html/bcp13)

2.3.4.2 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 is not useful.

2.33.3.2 2.3.4.3 Serving Binary Resources using the RESTful API

Binary resources behave slightly differently to from all other resources on the RESTful API. Specifically, when API:

  • When a read request is made for with a FHIR type in the Accept header (e.g. " application/fhir+xml " or " application/fhir+json ") the Binary resource is returned in the requested FHIR format. This applies even when the binary data itself has a FHIR mime type
  • The Binary resource that doesn't explicitly specify is always represented in the native FHIR content format when wrapped in a Bundle
  • The _format overrides the accept header and SHALL be interpreted as using the standard FHIR mime types, even if the more generic mime types "application/fhir+xml" or "application/fhir+json", are given as a value.
  • When the read request has some other type in the Accept header, then the content should be returned using with the content type stated in the resource. e.g. resource in the Content-Type header. E.g. if the content type in the resource is "application/pdf", then the content should be returned as a PDF directly. Note that The _summary parameter does not apply in this case.
  • 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 returned
  • 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 data 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 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, application/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 in the _summary parameter does not apply when native binary representation, the mime type normal resource metadata is not one available directly, though some of it is replicated in the standard 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. The content types. of the header is Binary.securityContext.reference

2.3.4.4 Image source for Narrative

Binary resources may be the target of img.src references in XHTML narrative, and also in markdown. See Image References for further details.

2.33.3.3 2.3.4.5 Security Considerations

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

2.3.4.6 Read

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

  • retrieving byte ranges
  • Finding the size of the content before retrieving it (though this can be achieved using a HEAD request )
  • Stream content from Binary?
  • generating content dynamically on the fly

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

2.33.3.4 2.3.4.7 Search

This specification does not support searching on Binary resources.

2.3.4.8 Patch

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

2.3.5 Search Parameters

Search parameters for this resource. See also the full list of search parameters for this resource , and check the Extensions registry for search parameters on extensions related to this resource. The common parameters also apply. See Searching for more information about searching in REST, messaging, and services.

(No search parameters for this resource)