Current Build

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

Implementable Technology Specifications Рабочая группаУровень зрелости: 5Статус голосования: Пробное использование

JSON-представление для ресурса описывается с помощью следующего формата:

{
  "resourceType" : "[Resource Type]",
  // from Source: element #1
  "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
  • Названия свойств чувствительны к регистру (хотя дубликаты, различающиеся только регистром, не используются)
  • Свойства можно указывать в любом порядке
  • XHTML указывается в виде экранированной строки
  • Объекты не могут быть пустыми. Если элемент присутствует в ресурсе, он ДОЛЖЕН иметь свойства, определенные для его типа, либо 1 или несколько расширений
  • Значения строковых свойств не могут быть пустыми. Либо свойство отсутствует, либо присутствует и содержит как минимум 1 символ
  • Символ R! означает, что элемент является обязательным - он должен присутствовать (либо в массиве должен быть как минимум один элемент)
  • В данном формате // используется для комментариев, но это нельзя использовать в JSON-экземплярах
  • Символьная кодировка всегда UTF-8
  • MIME-тип для этого формата - application/fhir+json.

Given the way extensions work, applications reading JSON resources will never enocunter unknown properties. However once an application starts trading with other appplications 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. Applications declare their behavior with regard to unknown elements using CapabilityStatement.acceptUnknown.

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

  • Имена членов JSON-объекта соответствуют именам элементов и атрибутов в XML, включая элементы, которые могут повторяться. Имена свойств чувствительны к регистру
  • Как и в XML, JSON объекты и массивы не бывают пустыми, а свойства are never empty, and properties никогда не содержат пустые значения (за исключением особого случая, описанного ниже). Следует опустить свойство, если оно пустое
  • В JSON символы табуляции не являются частью содержимого ресурса. Приложения могут сохранять символы табуляции во время обработки ресурсов, но не обязаны это делать. Обратите внимание, что от символов табуляции могут зависеть электронные цифровые подписи

There are differences to 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-элемента.
  • Элемент, который может повторяться, представляется в виде массива даже в том случае, если он не повторяется, чтобы процесс синтаксического разбора ресурса во всех случаях оставался одинаковым.
 <code>
   <coding>
     <system value="http://snomed.info/sct"/>
     <code value="104934005"/>
   </coding>
   <coding>
     <system value="http://loinc.org"/>
     <code value="2947-0"/>
   </coding>
 </code>

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

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

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

  • JSON-свойство с именем элемента, которое имеет JSON-тип числовой (number), логический (boolean) или строковый (string)
  • JSON-свойство со знаком _, добавленным в начало имени элемента, который, если присутствует, содержит id этого значения и/или расширения

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>

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

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

Примечание разработчика: Представление примитивных типов данных было разбито на две части с целью упрощения представления простых примитивных значений без идентификатора или расширений. Это действительно привело к издержкам, сделав представление атрибута 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, и family являются повторяющимися XML-элементами, поэтому они сериализуются в Array вне зависимости от того, повторяются они в данном случае или нет.
  • В части family элемента name атрибут id представлен в _family способом, описанным выше.
  • XHTML-содержимое элемента div, который есть в Narrative-элементе text, представлено в виде экранированной строки в JSON-свойстве value. Корневым элементом в XHTML должен быть <div> в пространстве имен XHTML.

Ресурс – это JSON-объект со свойством resourceType, который сообщает программе-анализатору, какой это тип ресурса:

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

Обратите внимание, что синтаксические анализаторы не могут полагаться на то, что свойство resourceType будет идти первым.

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

Для помощи в тестировании JSON-анализаторов приводится файл с примером, демонстрирующим многие крайние случаи.

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
  • Omit all properties that have a default value, if a default value is defined

This canonicalization method is identified by the URL http://hl7.org/fhir/canonicalization/json. The following additional canonicalization URLS 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
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 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.

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.