Current Build

Переводит компания Health Samurai . Приглашаем поучаствовать в русификации стандарта FHIR: GitHub , Email.

2.35 Ресурс Binary - Назначение

FHIR Infrastructure Work GroupMaturity Level: 5 NormativeSecurity Category: Not Classified 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 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.

Бывают ситуации, когда полезно или требуется работать с чистым бинарным содержимым с помощью тот же самого фреймворка, что и для других ресурсов. Обычно это случается, когда на бинарное содержимое ссылаются из других FHIR-ресурсов. Использование одного и того же фреймворка означает, что существующие серверы, соглашения по безопасности, библиотеки кода и т. п. могут обрабатывать дополнительное связанное содержимое. Ресурсы Binary используются, как правило, для обработки такого содержимого, как:

  • CDA -документы (т. е. с XDS)
  • PDF-документы
  • Изображения

Ресурс Binary может содержать любую информацию, будь то текст, изображение, PDF, ZIP-архив и т. п. Эти ресурсы обслуживаются в своей нативной форме в REST-интерфейсе, но также могут быть представлены в формате XML, JSON или других форматах, например при включении этих ресурсов в Bundle (используется, когда удобно включить их в непосредственно в ответ, а не оставить в виде ссылкок).

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

На этот ресурс ссылаются CatalogEntry и ImplementationGuide

Структура

ИмяФлагиКард.ТипОписание и ограниченияdoco
.. Binary NResourcePure binary content defined by a format other than FHIR
Элементы, определённые в прародителе: id, meta, implicitRules, language
... contentType Σ1..1codeMimeType of the binary content
MimeType (Required)
... securityContext Σ0..1Reference(Any)Identifies another resource to use as proxy when enforcing access control
... data 0..1base64BinaryThe actual content

doco Документация по этому формату

XML-шаблон

<Binary xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <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-шаблон

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


[ 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 Identifies another resource to use as proxy when enforcing access control
  fhir:Binary.data [ base64Binary ]; # 0..1 The actual content
]

Changes since R3

Binary
Binary.data
  • Renamed from content to data
  • Min Cardinality changed from 1 to 0

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 2 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.)

Структура

ИмяФлагиКард.ТипОписание и ограниченияdoco
.. Binary NResourcePure binary content defined by a format other than FHIR
Элементы, определённые в прародителе: id, meta, implicitRules, language
... contentType Σ1..1codeMimeType of the binary content
MimeType (Required)
... securityContext Σ0..1Reference(Any)Identifies another resource to use as proxy when enforcing access control
... data 0..1base64BinaryThe actual content

doco Документация по этому формату

XML-шаблон

<Binary xmlns="http://hl7.org/fhir"> doco
 <!-- from Resource: id, meta, implicitRules, and language -->
 <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-шаблон

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


[ 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 Identifies another resource to use as proxy when enforcing access control
  fhir:Binary.data [ base64Binary ]; # 0..1 The actual content
]

Changes since Release 3

Binary
Binary.data
  • Renamed from content to data
  • Min Cardinality changed from 1 to 0

See the Full Difference for further information

This analysis is available as XML or JSON.

See R3 <--> R4 Conversion Maps (status = 2 tests that all execute ok. All tests pass round-trip testing and all r3 resources are valid.)

 

See the Profiles & Extensions and the Альтернативные определения: Основное определение XML + JSON, XML Schema/Schematron + JSON Schema, ShEx (for Turtle) & the Анализ зависимостей

PathОписаниеТипСсылка
Binary.contentType The mime type of an attachment. Any valid mime type is allowed.RequiredMime Types

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.

Ресурсы Binary ведут себя несколько иначе, чем всех остальные ресурсы в RESTful API:

  • When a read request is made 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
  • When a read request is made 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 is always represented in the native FHIR 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 are given as a value.
  • When the read request has some other type in the Accept header, then the content should be returned with the content type stated in the 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. The _summary parameter does not apply in this case.
  • из-за способа работы веб-инфраструктуры не возможно ввести оющие правила об отношениях между полем "Accept" в запросе HTTP, и типом возвращаемого значения, вот почему по этому поводу нет никаких жестких правил. Однако замысел состоит в том, что если только на это нет специального запроса, то FHIR XML/JSON представление не возвращается.
  • When binary data is written to the server (create/update - POST or PUT), the data is accepted as is and treated as the 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 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.

Следует отметить, что в "родном" двоичном представлении обычные метаданные ресурса недоступны напрямую, хотя некоторые из них дублируются в заголовках HTTP ответа. В частности, следующие элементы ресурса дублируются в http-заголовках:

  • 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 of the header is Binary.securityContext.reference

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.

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 (hough 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.

This specification does not support searching on Binary resources.

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