Current Build

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

Implementable Technology Specifications Work GroupMaturity Level: 5Ballot Status: Normative

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.

The JSON representation for a resource is based on the JSON format described in STD 90 (RFC 8259) , and is described using this format:

{
  "resourceType" : "[Resource Type]",
  // from Source: property0
  "property1" : "<[primitive]>", // short description
  "property2" : { [Data Type] }, // short description
  "property3" : { // Short Description
    "propertyA" : { CodeableConcept }, // Short Description (Example)
  },
  "property4" : [{ // Short Description
    "propertyB" : { Reference(ResourceType) } // R!  Short Description
  }]
}

Используя этот формат:

  • Для создания валидного JSON-экземпляра ресурса, замените содержимое значений свойств желаемым контентом, как описано в правилах типов и описании значений, которые можно найти в значении свойства каждого элемента
  • В данном примере:
    1. property1 имеет примитивный тип данных; значение свойства будет таким же, как описанное для указанного типа
    2. property2 имеет сложный тип данных; значением свойства будет объект с содержимым, соответствующим описанию к указанному типу
    3. property3 - это объектное свойство, которое содержит дополнительные свойства (например propertyA; допустимые свойства перечислены (и также включают расширения при необходимости)
    4. property4 - это массив, который содержит элементы, которые, в свою очередь, являются объектами. Эти элементы могут быть любого из типов, перечисленных в пунктах 1-3
    5. propertyA is an example of an object property that has a binding to a value set - the Short description is a link to the value set. In addition, the binding strength is shown
    6. propertyB is an example of an object property that has a reference to a particular kind of resource
  • Названия свойств чувствительны к регистру (хотя дубликаты, различающиеся только регистром, не используются)
  • Property names SHALL be unique. Note: this is not explicitly stated in the original JSON specification,so stated for clarity here
  • Свойства можно указывать в любом порядке
  • XHTML указывается в виде экранированной строки
  • Объекты не могут быть пустыми. Если элемент присутствует в ресурсе, он ДОЛЖЕН иметь свойства, определенные для его типа, либо 1 или несколько расширений
  • Значения строковых свойств не могут быть пустыми. Либо свойство отсутствует, либо присутствует и содержит как минимум 1 символ
  • Символ R! означает, что элемент является обязательным - он должен присутствовать (либо в массиве должен быть как минимум один элемент)
  • В данном формате // используется для комментариев. Хотя // допустимы в Javascript, их нельзя использовать в JSON-экземплярах независимо от того, игнорируют ли их конкретные приложения
  • Символьная кодировка всегда UTF-8
  • MIME-тип для этого формата - application/fhir+json.

Given the way extensions work, applications reading JSON resources will never encounter unknown properties. However, once an application starts trading with other applications that conform to later versions of this specification, unknown properties may be encountered. Applications MAY choose to ignore unknown properties in order to foster forwards compatibility in this regard, but may also choose not to.

JSON-формат подобен XML-формату:

  • Имена членов JSON-объекта соответствуют именам элементов и атрибутов в XML, включая элементы, которые могут повторяться. Имена свойств чувствительны к регистру The names for the JSON object members are the same as the names of the elements and attributes in XML, including elements that may repeat. Property names are case sensitive
  • Как и в XML, JSON объекты и массивы не бывают пустыми, а свойства are never empty, and properties никогда не содержат пустые значения (за исключением особого случая, описанного ниже). Следует опустить свойство, если оно пустое Just as in XML, JSON objects and arrays are never empty, and properties never have null values (except for a special case documented below). Omit a property if it is empty
  • В JSON символы табуляции не являются частью содержимого ресурса. Приложения могут сохранять символы табуляции во время обработки ресурсов, но не обязаны это делать. Обратите внимание, что от символов табуляции могут зависеть электронные цифровые подписи JSON whitespace is not part of the contents of a resource. Applications MAY preserve the whitespace when handling resources, but are not required to do so. Note that digital signatures may depend on the whitespace

There are differences from XML:

  • В JSON-представлении нет пространств имен
  • Тип ресурса представляется в JSON по-другому - не как имя базового объекта (котрого в JSON нет), а как свойство resourceType
  • Порядок следования свойств объекта в JSON-представлении не имеет значения, хотя внутри массива порядок должен поддерживаться
  • JSON не имеет различия в обозначении атрибута и элемента, поэтому атрибуты (e.g. id, value) обрабатываются иначе (см. ниже)
  • В JSON есть обозначение массива, используемое для представления повторяющихся элементов. Обратите внимание, что массивы используются, когда элемент может повторяться, даже если он не повторяется в конкретном случае
  • XHTML-элемент <div> в типе данных Narrative представлен как отдельная экранированная строка XHTML. Это делается для того, чтобы избежать проблем в JSON со смешанным содержимым и проч. XHTML ДОЛЖЕН по-прежнему соответствовать правилам, описанным для Narrative

Формат JSON для ресурсов приближен к стандартному XML-формату, что делает взаимное преобразование легкодоступным, поэтому XPath-запросы легко мапятся на запросы JSON-структур. Однако различия – особенно с повторяющимся элементом, которого невозможно избежать – означают, что универсальные преобразователи XML --> JSON не в состоянии выполнить эту операцию корректно. Эти справочные платформы предлагают функциональность по преобразованию XML <--> JSON, которая учитывает эти специфичные для FHIR технические детали.

Элемент с максимальным кардинальным числом >1 (например x..* в определениях) может встречаться больше одного раза в экземпляре. В XML это делается простым повторением XML-элемента множество раз. В JSON это делается с помощью типа array. Обратите внимание, что:

  • Имя массива указывается в единственном числе – так же как и XML-элемента. The name of the array is singular - the same as the XML element
  • Элемент, который может повторяться, представляется в виде массива даже в том случае, если он не повторяется, чтобы процесс синтаксического разбора ресурса во всех случаях оставался одинаковым. An item that may repeat is represented as an array even in the case that it doesn't repeat so that the process of parsing the resource is the same either way
 <code>
   <coding>
     <system value="http://snomed.info/sct"/>
     <code value="104934005"/>
   </coding>
   <coding>
     <system value="http://loinc.org"/>
     <code value="2947-0"/>
   </coding>
 </code>

is represented in JSON like this:

{
 "coding": [
   {
     "system" : "http://snomed.info/sct",
     "code" : "104934005"
   },
   {
     "system" : "http://loinc.org",
     "code" : "2947-0"
   }
 ]
}

FHIR-элементы с примитивными типами данных представляются в двух частях:

  • JSON-свойство с именем элемента, которое имеет JSON-тип числовой (number), логический (boolean) или строковый (string) A JSON property with the name of the element, which has a JSON type of number, boolean, or string
  • JSON-свойство со знаком _, добавленным в начало имени элемента, который, если присутствует, содержит id этого значения и/или расширения a JSON property with _ prepended to the name of the element, which, if present, contains the value's id and/or extensions

FHIR-типы integer и decimal представляются JSON-типом number, FHIR-тип boolean – как JSON boolean, а все остальные типы представляются как JSON-тип string, имеющий то же содержимое, что указано для соответствующего типа данных. Символы табуляции всегда являются значимыми (т. е. пробелы в начале и в конце для нестроковых типов не допускаются).

 <code value="abc"/> <!-- code -->
 <date value="1972-11-30"/> <!-- dateTime -->
 <deceased value="false" /> <!-- boolean -->
 <count value="23" />  <!-- integer -->

в JSON представляется так:

 "code" : "abc",
 "date" : "1972-11-30",
 "deceased" : false,
 "count" : 23

При использовании JavaScript JSON.parse() реализации обратите внимание, что JavaScript изначально поддерживает только один числовой тип данных, которым является число с плавающей точкой (floating point number). Это может привести к потере точности для чисел FHIR. В частности, нули после точки будут потеряны, например 2.00 превратится в 2. FHIR-тип данных decimal определен таким образом, чтобы точность, включая нули на кнце, сохранялась в целях представления, поскольку это часто является критичным требованием для корректного представления клинических измерений. Реализациям следует рассмотреть использование кастомного парсерав и библиотеки больших чисел (например https://github.com/jtobey/javascript-bignum ) для удовлетворения этих требований.

 

Если значение имеет атрибут id или расширения, то оно представляется следующим образом:

 <birthDate id="314159" value="1970-03-30" >
   <extension url="http://example.org/fhir/StructureDefinition/text">
     <valueString value="Easter 1970"/>
   </extension>
 </birthDate>

is represented in JSON as:

 "birthDate": "1970-03-30",
 "_birthDate": {
   "id": "314159",
   "extension" : [ {
      "url" : "http://example.org/fhir/StructureDefinition/text",
      "valueString" : "Easter 1970"
   }]
 }

Примечание: Если примитив имеет атрибут id или расширение, но не имеет value, то указывается только свойство со знаком _.

В случае, когда примитивный элемент может повторяться, это представляется двумя массивами. Для заполнения обоих массивов используется JSON-значение null, чтобы привести в соответствие идентификатор и/или расширение с его значением в первом массиве, как продемонстрировано в этом примере:

 <code value="au"/>
 <code value="nz">
   <extension url="http://hl7.org/fhir/StructureDefinition/display">
     <valueString value="New Zealand a.k.a Kiwiland"/>
   </extension>
 </code>

в JSON представляется так:

 "code": [ "au", "nz" ],
 "_code": [
   null,
   {
     "extension" : [ {
        "url" : "http://hl7.org/fhir/StructureDefinition/display",
        "valueString" : "New Zealand a.k.a Kiwiland"
     }]
   }
  ]

Примечание: когда у одного из повторяющихся элементов нет значения (value), в первом массиве для него указывается значение null. Когда у элемента есть значение, но нет расширения/идентификатора, во втором массиве на месте этого элемента будет стоять null.

Implementation Note: Представление примитивных типов данных было разбито на две части с целью упрощения представления простых примитивных значений без идентификатора или расширений. Это действительно привело к издержкам, сделав представление атрибута id и расширений более неуклюжим, однако они оба редко используются с примитивными типами данных.

Элементы и сложные типы данных (типы, содержащие именованные элементы других типов) представляются с помощью JSON-объекта, содержащего соответствующий элемент для каждого элемента в типе данных. Композиции могут иметь атрибуты id, которые преобразовываются в значения JSON-элементов объекта таким же способом, как описано для примитивов. Например:

<Patient>
  <text>
    <status value="generated" />
    <div xmlns="http://www.w3.org/1999/xhtml"><p>...</p></div>
  </text>
  <name>
    <use value="official" />
    <given value="Karen" />
    <family id="a2" value="Van" />
  </name>
</Patient>

в JSON представляется так:

{
  "name" : [{
    "use" : "official" ,
    "given" : [ "Karen" ],
    "family" :  "Van",
    "_family" : {"id" : "a2"}
   }],
  "text" : {
    "status" : "generated" ,
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
  }
}

На что здесь необходимо обратить внимание:

  • given является повторяющимся XML-элементом, поэтому он сериализуется в массив вне зависимости от того, повторяется он в данном случае или нет.
  • В части family элемента name атрибут id представлен в _family способом, описанным выше. In the family part of name, the id is added represented in _family as described above
  • XHTML-содержимое элемента div, который есть в Narrative-элементе text, представлено в виде экранированной строки в JSON-свойстве value. Корневым элементом в XHTML должен быть <div> в пространстве имен XHTML. The XHTML content in the div element which is in the Narrative element text is represented as an escaped string in the value property in JSON. The xhtml root element needs to be a <div> in the xhtml namespace

Ресурс – это JSON-объект со свойством resourceType, который сообщает программе-анализатору, какой это тип ресурса: A resource is a JSON object with a property resourceType which informs the parser which resource type this is:

{
  "resourceType" : "Patient",
  "text" : {
    "status" : "generated" ,
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>...</p></div>"
  }
  // etc...
}

Обратите внимание, что синтаксические анализаторы не могут полагаться на то, что свойство resourceType будет идти первым. Note that parsers cannot assume that the resourceType property will come first.

Implementation Note: Это является проблемой для некоторых сериализаторов вида JSON -> Object , которые предполагают, что свойство resourceType действительно идет первым, включая Json.NET . Однако некоторые JSON-генераторы не дают авторским приложениям управлять порядком значений свойств, поэтому эти реализации не могут взаимодействовать с реализациями, которые делают предположения о порядке. Учитывая, что JSON заявляет, что значения свойств являются неупорядоченной таблицей пар name/value, данная спецификация не может требовать, чтобы свойства шли в каком-то определенном порядке, хотя реализаторы могут зафиксировать порядок свойств, если у них есть такая возможность (и ссылочные платформы, предоставленные в этой спецификации, делают это).

Для помощи в тестировании JSON-анализаторов приводится файл с примером, демонстрирующим многие крайние случаи. There is a sample file with many edge cases to help test JSON parsers.

Resources and/or Bundles may be digitally signed (see Bundle and Provenance).

This specification defines the following method for canonicalizing FHIR resources, when represented as JSON:

  • No whitespace other than single spaces in property values and in the xhtml in the Narrative
  • Order properties alphabetically

This canonicalization method is identified by the URI http://hl7.org/fhir/canonicalization/json. The following additional canonicalization URIs are also defined:

http://hl7.org/fhir/canonicalization/json#data The narrative (Resource.text) is omitted prior to signing (note the deletion is at Resource.text, not Resource.text.div)
http://hl7.org/fhir/canonicalization/json#static In addition to narrative (Resource.text), the Resource.meta element is removed. This makes the signature robust as the content is moved from server to server, or workflow and access tags are added or removed. Note that workflow and security tags may contain information important to the handling of the resource, so meta elements should be protected from tampering by other means if unsigned.
http://hl7.org/fhir/canonicalization/json#narrative This method only retains the Resource.id and Narrative elements
http://hl7.org/fhir/canonicalization/json#document The signs everything in a Bundle, except for the Bundle.id and Bundle.metadata on the root Bundle (allows for a document to be copied from server to server)

These canonicalization methods allow system the flexibility to sign the various portions of the resource that matter for the workflow the signature serves. These canonicalization algorithms do not work for enveloped signatures. This will be researched and addressed in a future release. This specification may define additional canonicalizations in the future, and other specifications might also define additional canonicalization methods.

Implementation Note: One consequence of signing the document is that URLs, identifiers and internal references are frozen and cannot be changed. This might be a desired feature, but it may also cripple interoperability between closed ecosystems where re-identification frequently occurs. For this reason, it is recommended that systems consider carefully the impact of any signature processes. The impact of signatures on Document bundles and their related processes is the most well understood use of digital signatures.