Uzbekistan Digital Health Platform, опубликовано Ministry of Health of the Republic of Uzbekistan. Это руководство не является санкционированной публикацией; это непрерывная сборка для версии 0.5.0, созданной FHIR (HL7® FHIR® Standard) CI Build. Эта версия основана на нынешнем содержании https://github.com/uzinfocom-org/digital-health-ig/ и регулярно изменяется. Смотрите каталог опубликованных версий

General guidance

​На этой странице представлены переводы с языка оригинала, на котором былонаписано руководство. Информацию об этих переводах и инструкции попредоставлению отзывов о переводах можно найти здесь.

Общие правила, применимые ко всем профилям UZ Core. В этом разделе даны ответы на вопросы, которые чаще всего возникают у разработчиков: какие метаданные должны присутствовать в каждом ресурсе, что делать при отсутствии значения элемента, как кодировать единицы измерения, как объединять ресурсы в Bundle и как Платформа сообщает об ошибках.

Обязательные метаданные ресурса

​Каждый ресурс, передаваемый через Платформу, помимо клинических данных должен содержать:

• meta.profile - канонический URL (с версией) профиля UZ Core, которому, согласно заявлению ресурса, он соответствует. По этому URL сервер определяет, по каким правилам валидировать ресурс.
• id - логический идентификатор ресурса на сервере. Новому ресурсу его назначает сервер.

{
  "resourceType": "Observation",
  "id": "abc-123",
  "meta": {
    "profile": ["https://dhp.uz/fhir/core/StructureDefinition/uz-core-observation"],
    "lastUpdated": "2026-05-30T09:12:00+05:00"
  }
}

Данные передаются в формате JSON с кодировкой UTF-8.

Отсутствующие и скрытые данные

Следует различать ситуации "у меня нет значения" и "значения не существует". FHIR позволяет явно указать, какая из них имеет место:

• Значение просто отсутствует - не передавайте элемент. Не отправляйте пустую строку или значение-заполнитель. Это допустимо для любого необязательного элемента с кратностью 0.., включая необязательные элементы Must Support.
• Элемент обязателен, но значение действительно неизвестно - элемент с кратностью 1.. нельзя пропустить, поэтому используйте предусмотренный для ресурса механизм указания неизвестного значения: расширение data-absent-reason в элементе (пример) либо код unknown, если он предусмотрен привязанным ValueSet (например, для кодированного элемента, привязанного к ValueSet, который включает код unknown).
• Никогда не выдумывайте данные, чтобы выполнить ограничение. Вымышленная дата рождения или фиктивный идентификатор хуже, чем явно зафиксированное отсутствие данных.

Некоторые профили содержат отдельный элемент data-absent-reason - например, UZ Core Patient допускает расширение data-absent-reason в элементе value идентификатора для редких случаев, когда недоступен даже сам идентификатор.

В разделе Must Support описано, как это связано с флагом S.

Единицы измерения и количественные значения

Для кода единицы измерения в числовых измерениях используется UCUM (http://unitsofmeasure.org):

{
  "valueQuantity": {
    "value": 7.2,
    "unit": "%",
    "system": "http://unitsofmeasure.org",
    "code": "%"
  }
}

• Всегда заполняйте system и code машиночитаемым кодом UCUM, а не только человекочитаемой строкой unit.
• Если результат указывается без единицы измерения (безразмерное количество, титр или отношение), всё равно передавайте value; не передавайте code/system только тогда, когда единица UCUM действительно отсутствует.
• Референсные диапазоны и флаги интерпретации (normal / high / low / critical) указываются соответственно в Observation.referenceRange и Observation.interpretation.

Адреса

Адреса используются в нескольких ресурсах (Patient, Practitioner, Organization, Location). UZ Core поддерживает как адреса в Узбекистане, так и международные адреса.

Адрес в Узбекистане

Для административно-территориальных единиц используйте кодированные значения из официальных реестров. Платформа проверяет, что область, район и город соответствуют кодам системы управления цифровыми данными о населении (DPM):

{
  "address": [{
    "use": "home",
    "type": "physical",
    "country": "UZ",
    "state": "1727",            // Region code from https://terminology.dhp.uz/fhir/core/ValueSet/state-vs (e.g., 1727 for Tashkent Region)
    "district": "1727220",      // District code from https://terminology.dhp.uz/fhir/core/ValueSet/regions-vs (e.g., 1727220 for Bekobod district)
    "city": "17150085",         // Mahalla code from https://terminology.dhp.uz/fhir/core/ValueSet/mahalla-vs (citizens' assembly)
    "line": ["Amir Temur ko'chasi"],
    "text": "Yangi Sergeli mahallasi, Amir Temur ko'chasi, 15-uy, 42-xonadon"
  }]
}

Международный адрес

Для адресов за пределами Узбекистана административно-территориальные единицы указываются свободным текстом без обязательной привязки к ValueSet, что позволяет гибко представлять структуру иностранных адресов:

{
  "address": [{
    "use": "home",
    "type": "physical",
    "country": "US",
    "state": "California",             // Free text
    "district": "Los Angeles County",  // Free text
    "city": "Los Angeles",             // Free text
    "line": ["123 Main Street", "Apt 4B"],
    "postalCode": "90001"
  }]
}

Терминология и многоязычные обозначения

• ​Используйте коды из привязанного ValueSet с учётом степени обязательности привязки.
• ​Обозначения (отображаемые наименования на узбекском / русском / английском языках) предназначены только для отображения; смысл передаётся элементом code. В разделе "Основы FHIR" описано, как UZ CodeSystems и терминологические дополнения HL7 предоставляют эти многоязычные обозначения.
• Коды можно проверить на терминологическом сервере Платформы с помощью стандартной операции $validate-code:

POST [base]/ValueSet/$validate-code
{ "resourceType": "Parameters",
  "parameter": [
    { "name": "url", "valueUri": "https://dhp.uz/fhir/core/ValueSet/uz-core-diagnosis" },
    { "name": "system", "valueUri": "http://hl7.org/fhir/sid/icd-10" },
    { "name": "code", "valueCode": "E11" } ] }

Системы идентификаторов (не терминологические системы) описаны в разделе "Системы идентификаторов".

Bundle: document, transaction и searchset

Выбирайте Bundle.type в зависимости от выполняемой операции:

Если несколько ресурсов связаны между собой, передавайте их вместе в одном Bundle, а не отдельными несогласованными запросами. Конкретные примеры transaction Bundle и document Bundle приведены в разделе "Рабочие процессы".

Создание, обновление и удаление

• Платформа поддерживает стандартные REST-взаимодействия: GET (чтение/поиск), POST (создание), PUT (обновление), PATCH (частичное обновление) и DELETE. Точный набор взаимодействий для каждого ресурса объявлен в CapabilityStatement.
• Используйте логическое, а не физическое удаление. Клинические данные не удаляются посредством удаления ресурса. Чтобы вывести запись из использования, измените её статус: в зависимости от ситуации установите entered-in-error, inactive, revoked или эквивалентный для данного ресурса статус. Например, отозванный Goal переводится в cancelled/completed, отозванный Consent - в inactive, а ошибочная клиническая запись - в entered-in-error. Ресурс и история его изменений остаются доступными для запросов.
• Конкурентное обновление. При обновлении используется оптимистическая блокировка. Сохраните ETag, полученный при последнем чтении, и передайте его в заголовке If-Match при обновлении. Если после чтения ресурс был изменён другим клиентом, версии не совпадут и сервер вернёт 412 Precondition Failed ("Version is mismatch"). Повторно прочитайте ресурс и повторите запрос - см. раздел Конкурентное обновление.
• Идемпотентность. Для операций рабочих процессов и финансовых операций, которые не должны дублироваться при повторной отправке запроса, используйте условное создание/обновление, чтобы повторный запрос не создал второй ресурс.

Ошибки

Если запрос завершается ошибкой - из-за валидации, авторизации или конфликта - сервер возвращает OperationOutcome с уровнем серьёзности, кодом и человекочитаемым диагностическим сообщением:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "required",
    "diagnostics": "Patient.identifier: minimum required = 1, but only found 0",
    "expression": ["Patient.identifier"]
  }]
}

Распространённые коды: required/value/invariant (ресурс не прошёл валидацию по профилю), code-invalid (код отсутствует в привязанном ValueSet), forbidden (запрос отклонён из-за правил авторизации или согласия - см. рекомендации по управлению доступом), а также 412 с кодом invalid (конфликт версии If-Match - см. раздел Конкурентное обновление). Чтобы определить элемент, вызвавший ошибку, прочитайте diagnostics и expression.

Что изучить дальше

• Как пользоваться этим руководством и Must Support - принятые соглашения.
• Рабочие процессы - сквозные сценарии с реальными Bundle.
• Системы идентификаторов - URI систем идентификаторов.