Валидация на соответствие справочникам

FTR (терминологический репозиторий FHIR) — это открытая спецификация для структуры репозитория, форматов и алгоритмов для распространения терминологий FHIR в виде наборов значений.

Базовой единицей распространения является файл терминологии, который содержит расширенный набор значений и системы кодирования, используемые для развёртки этого набора значений. Развёрнутый набор значений представляет собой коллекцию всех понятий (концептов), на которые ссылается этот набор значений. Каждый концепт должен иметь как минимум два элемента — систему и код, а также может содержать и другие произвольные свойства.

Создание наборов значений выходит за рамки этой спецификации.

FTR определяет следующие сущности:

• Формат файла терминологии (Terminology File) — для хранения содержимого конкретной версии ValueSet.
• Формат патча файла терминологии — изменения между двумя версиями ValueSet.
• Формат тега файла терминологии — именованная ссылка на конкретную версию и цепочку исправлений.
• Формат индекса тегов — индекс всех наборов значений с определенным тегом.
• Алгоритм обновления файла терминологии — как обновить файл терминологии с помощью индекса тегов и тега файла терминологии.
• Алгоритм синхронизации тегов — насколько эффективно синхронизировать множество файлов терминологии.
• Алгоритм публикации файла терминологии — как следует публиковать файл терминологии.

Можно сохранить полученный FTR в S3-подобное хранилище или в обычной файловой системе. FTR наполняется и распространяется через zen-пакеты.

Структура репозитория

FTR — это обычный каталог, содержащий каталоги модулей (fhir.r4 или loinc). Каталог каждого модуля содержит каталог vs/ с наборами значений и каталог tags/ с индексами тегов.

 fhir/ # module
      - tags/ # tags
        - r5.ndjson.gz # tag indexes
        - r4.ndjson.gz
      - vs/ 
        - patient.gender/ # valueset
          - tag.r4.ndjson.gz # vs tag
          - tag.r5.ndjson.gz
          - tf.bc7623b7a94ed3d8feaffaf7580df3eca4f5f5ca.ndjson.gz # vs file
          - tf.e3b0c44298fc1c149afbf4c8996fb92427ae41ca.ndjson.gz
          - patch.bc7623b7a.7ae41ca.ndjson.gz # vs patch
    loinc
      - tags/
        - main.ndjson.gz
      - vs/ 
        - loinc/
          - tag.main.ndjson.gz
          - tf.bc7623b7a94ed3d8feaffaf7580df3eca4f5f5ca.ndjson.gz

Файл терминологии (TF) Файл терминологии (TF) представляет собой сжатый gzip-файл ndjson. Первые строки этого файла — это ресурсы CodeSystems и ValueSet, а остальные — это ресурсы Concept. Строки ресурса Concept должны быть отсортированы лексикографически по шаблону {{system}}-{{code}}. JSON должен быть в каноническом формате JSON, то есть с отсортированными ключами и без пробелов, чтобы гарантировать воспроизводимый хэш SHA256 файлов с одинаковым содержимым. Имя файла терминологии должно соответствовать шаблону vs.{hash}.ndjson.gz, где хеш — это хэш SHA256 сжатого gzip содержимого файла.

Файл исправления терминологии (TFP) и алгоритм сравнения Алгоритм сравнения Если у вас есть две версии файлов терминологии, вы можете сгенерировать файл исправления (TFP) за один прогон по следующему алгоритму:

reserve_lines_with_codesystems_and_valueset()
loop( c1 = next_concept(tf1), c2 = next_concept(tf2))
 case
  when is-nil(c1) && is-nil?(c2)
   result
  when is-nil(c1)
   new_concept(c2)
   recur(c1, next_concept(tf2))
  when is-nil(c2)
   remove_concept(c1)
   recur(next_concept(tf1), nil)
  when c1.code&system = c2.code&system
   when c1 not equal c2
    update_concept(c2)
    recur(next_concept(tf1), next_concept(tf2))
  when c1.code&system < c2.code&system
   remove_concept(c1)
   recur(next_concept(tf1), c2)
  when c1.code&system > c2.code&system
   new_concept(c2)
   recur(c1, next_concept(tf2))

c1.code&system < c2.code&system and c1.code&system > c2.code&system означает, что вы должны сравнивать эти строки лексикографически.

Файл исправления терминологии Файл исправлений терминологии (TPF) представляет собой сжатый gzip ndjson-файл. Первая строка этого файла представляет собой объект JSON, содержащий имя ValueSet, для которого был создан этот файл исправления, а остальные — объекты JSON с операциями, описывающими, как получить новую версию файла терминологии и содержимое ресурса Concept.

TPF содержит всего 3 типа операций:

• add — добавляет новый концепт
• update — обновляет существующие свойства концепта
• remove — удаляет существующий концепт

Пример файла исправления терминологии

  {"name":"myvs"}
  {"op": "add",    "code":"c1", "display":".."}
  {"op": "remove", "code":"c2", "display":".."}
  {"op": "update", "code":"c3", "display":".."}

Файл тегов ValueSet (VST) Файл тега ValueSet представляет собой файл ndjson, сжатый gzip. Где первая строка — это хэш последней версии ValueSet, а остальные — указатели на файлы патчей. Он используется для расчета эффективного исправления между несмежными версиями.

{"tag":"fhir.v4", "hash":"{hash-3}"}
{"from": "{hash-1}", "to":"{hash-2}"}
{"from": "{hash-2}", "to":"{hash-3}"}

Файл индекса тегов (TI) Файл индекса тегов представляет собой таблицу всех наборов значений с определенным тегом и их фактических хэшей, отсортированных по имени набора значений. Он предназначен для быстрой проверки того, не изменилось ли что-либо в теге, и расчета плана массовых исправлений. Клиент может сохранить индекс последнего тега. Когда клиент хочет проверить, что «что-то изменилось», он может сравнить сохраненный индекс тега с текущим индексом тега. Когда индексы тегов не равны, клиент может загрузить файл индекса и, используя предыдущие хэши VS, определить, какой VS следует обновить. Чтобы обновить клиент VS, загрузите VST и выполните поиск исправлений, которые будут применяться к клиентской версии VS, или клиент может просто загрузить полную версию, указанную в VST.

Пример файла индекса тегов

{"name": "module.myvs-1", "hash":"...."}
{"name": "module.myvs-2", "hash":"...."}

Алгоритм обновления файла терминологии

Алгоритм синхронизации тегов

Алгоритм публикации файлов терминологии

Для того, чтобы опубликовать файл терминологии под определенным тегом, выполните следующее:

• генерировать файл терминологии
• проверить, что его нет в текущем репозитории — и загрузить его
• проверить файл тегов этого VS, указывающего на эту версию
• если нет:
  • сгенерировать файл патча из последней версии
  • обновить TFP с новым хешем и миграцией
• обновить файл TI и его хэш-файл

Необходимо скачать файл zen.jar по ссылке https://github.com/HealthSamurai/ftr/releases/latest/download/zen.jar

Создайте директорию project со следующей структурой:

project/
  zen-package.edn #Package deps declaration
  resources/
    icd-10.csv #CSV source file
  zrc/
    system.edn #System entrypoint importing a ValueSet definion
    diagnosis.edn # ValueSet definition

Содержимое файла zen-package.edn:

{:deps {}}

Содержимое файла zrc/system.edn:

{:ns system
 :import #{aidbox diagnosis}
 
 box
 {:zen/tags #{aidbox/system}}}

Содержимое файла zrc/diagnosis.edn:

{:ns diagnosis
 :import #{zen.fhir}
 
 diagnosis-vs
 {:zen/tags #{zen.fhir/value-set},
  :zen.fhir/version "0.5.0",
  :uri "diagnosis-vs",
  :ftr
  {:module "ig",
   :source-url "resources/icd-10.csv",
   :ftr-path "ftr",
   :tag "v1",
   :source-type :flat-table,
   :extractor-options
   {:format "csv",
    :csv-format {:delimiter ";", :quote "'"},
    :header false,
    :data-row 0,
    :mapping {:concept {:code {:column 2}, :display {:column 3}}},
    :code-system {:id "icd10", :url "http://hl7.org/fhir/sid/icd-10"},
    :value-set
    {:id "icd10", :name "icd10.accidents", :url "diagnosis-vs"}}}}}

Создайте файл resources/icd-10.csv следующего содержания:

10344;20;XX;External causes of morbidity and mortality;;;1;
16003;2001;V01-X59;Accidents;10344;;1;
15062;20012;W00-X59;Other external causes of accidental injury;16003;;1;10/07/2020
11748;2001203;W50-W64;Exposure to animate mechanical forces;15062;;1;
11870;2001203W64;W64;Exposure to other and unspecified animate mechanical forces;11748;;1;
11871;2001203W640;W64.0;Exposure to other and unspecified animate mechanical forces home while engaged in sports activity;11870;;1;
11872;2001203W641;W64.00;Exposure to other and unspecified animate mechanical forces, home, while engaged in sports activity;11871;;1;
11873;2001203W641;W64.01;Exposure to other and unspecified animate mechanical forces, home, while engaged in leisure activity;11871;;1;

Инициализируйте директорию как гит-репозиторий и сделайте коммит:

git init && git add --all && git commit -m "init"

Замените PATH_TO_JAR на абсолютный путь к файлу zen.jar.

Выполните следующую команду в директории проекта:

java -jar PATH_TO_JAR build-ftr

Закоммитьте FTR-директорию:

git add . && git commit -m "Build ftr"

Теперь можно провалидировать ресурс на соответствие справочнику командой:

java -jar PATH_TO_JAR validate '[fhir-ru/Patient]' '{:gender "male"}'