Quartz 4

FHIR Implementation Guide (IG)

draft
Not verified

4 min read

Implementation Guide — это публикуемый пакет того что нужно для реализации одного use case на FHIR. Не один файл, а коллекция conformance-ресурсов (profiles, extensions, value sets, code systems, capability statement) + markdown-страницы (scenarios, walkthrough, security) + examples. Аналогия из обычной разработки: «спецификация API» vs «один endpoint». IG — это спецификация всей экосистемы вокруг конкретной задачи (US-рынок, oncology, payer-data-exchange, и т.д.).

Где живёт в данных

  • В исходниках — IG-репозиторий обычно отдельный (HL7/US-Core, HL7/fhir-us-mcode-ig). Внутри:
    • input/fsh/ или input/resources/ — conformance resources (FSH или JSON)
    • input/pagecontent/ — markdown human-readable страницы
    • input/examples/ — пример-ресурсы для иллюстрации и тестов
    • sushi-config.yaml — конфиг IG (имя, версия, dependencies)
  • После сборки — три artefact’а:
    • HTML-сайт (build.fhir.org/ig/HL7/US-Core/ — публичный, кликабельный)
    • NPM-пакет (hl7.fhir.us.core на npm + simplifier.net registry) — для подключения как dependency в других IG’ах
    • Validation pack — JSON-bundle SDs для FHIR validator’а

Что входит в IG

ЧастьЧто описываетИсточник в репо
Profiles (StructureDefinition)Какие resource shapes мы определяем (Patient, Observation, Composition, etc)input/fsh/profiles/ или input/resources/StructureDefinition-*.json
ExtensionsCustom поля, которые добавляем к стандартным ресурсамinput/fsh/extensions/
ValueSets / CodeSystemsКакие коды разрешены / используютсяinput/fsh/valuesets/, input/fsh/codesystems/
CapabilityStatementКакие операции / search-параметры FHIR-сервер обязан поддерживатьinput/fsh/capabilities/
OperationDefinitionsCustom операции типа $everything, $validateредко, обычно ничего
SearchParametersCustom search-параметры (если стандартных не хватает)редко
Markdown-страницыHuman-readable доки: scenarios, walkthrough, examples, security guidanceinput/pagecontent/
ExamplesРеальные JSON-ресурсы как test fixtures и иллюстрацииinput/examples/

IG Publisher — компилятор всего этого

IG Publisher — Java jar, который читает структуру выше и собирает:

  1. HTML-сайт с полным навигационным деревом, отрендеренными SDs (с таблицами cardinality / must-support), отрендеренными differential’ами относительно базы, кликабельными примерами, FHIR validation отчётами на examples.
  2. NPM-пакет (hl7.fhir.us.core-<version>.tgz) который можно загрузить в simplifier.net или установить как dependency в зависимом IG.
  3. Validation pack (package.tgz со всеми SDs) — это package keyword в FHIR validator’е.

Команда сборки обычно одна:

java -jar publisher.jar -ig ig.ini

Под капотом: SUSHI (FSH → JSON) → IG Publisher (JSON → HTML/NPM/validation).

Примеры реальных IGs

Открытые публичные IGs, в которые можно ткнуться:

Каждый IG — это репо в HL7/<name> или <org>/<name> на GitHub, открытый исходник + автогенерируемый HTML-сайт.

Когда IG публикуют

IG это публичный contract, а не внутренний артефакт. Команда публикует IG когда хочет:

  • Сказать партнёрам / интеграторам: «вот так должны выглядеть ресурсы, которые мы отдаём / принимаем»
  • Получить регулятивное соответствие (US HTI-1 requires US Core IG conformance)
  • Войти в discoverability (simplifier.net hub) — чтобы другие команды могли найти твой IG и переиспользовать
  • Получить validation pack для FHIR validator’а out-of-the-box

Внутренние команды без публикации обычно живут на stub-IG в личном репо — собирают SDs и используют локально (для codegen / validation), без публикации HTML-сайта.

Versioning и dependencies

IG версионируется semver (1.0.0, 2.0.0). Может зависеть от других IG’ов:

# sushi-config.yaml
id: bloodgpt.fhir.profiles
version: 0.1.0
dependencies:
  hl7.fhir.r4.core: 4.0.1        # base FHIR R4
  hl7.fhir.us.core: 7.0.0        # если конформимся US Core

NPM-style resolution. SUSHI / IG Publisher разворачивают зависимости в свой fhir-cache.

Наш текущий статус

  • Своего IG нет. Vanilla R4, conformance ни к чему не декларируем.
  • Conventions из US Core применяем неявно (например, Condition.category = problem-list-item) — но без meta.profile, без validation pack.
  • Если решим собирать свой IG (см. formalize-fhir-profiles) — это отдельный репозиторий bloodgpt-fhir-profiles, отдельный CI, отдельный published artefact. Не примешивается в monorepo (slow build, отдельная конвенция, отдельная команда могла бы поддерживать).

Когда нам понадобится IG

Триггеры (в порядке вероятности):

  1. Второй партнёр который хочет читать наши данные — даём ему URL нашего IG как контракт.
  2. AI prompt’ы для LLM-генерации FHIR — можно загрузить SDs из IG как spec в context промпта.
  3. Apple Health Records integration → требуется US Core conformance или IPS conformance, проще claim’ить через meta.profile + публикация stub IG.
  4. US HTI-1 / regulated US market entry → обязательно.
  5. Discoverability в FHIR community (publishing на simplifier.net) — но это уже маркетинговое решение.

До этих триггеров IG не нужен — внутренние профили могут жить в bloodgpt-fhir-profiles/ без публикации HTML-сайта.

Открытые вопросы

  • Стартовать с stub-IG (только SDs, без markdown / HTML publication) или сразу полноценный IG с walkthrough?
  • Где hostить опубликованный IG — simplifier.net (default community-place), собственный домен build.bloodgpt.com/ig/, GitHub Pages?
  • Когда мы добавим US Core / IPS dependency — это уже compliance claim, нужно ли всё проверять валидатором в CI?

Связано

  • fhir-conformance-resources — семейство ресурсов, из которых состоит IG
  • fhir-profiling — главное содержимое IG (StructureDefinition profiles)
  • fsh — DSL для авторства IG-контента
  • fhir-code-generation — что можно делать с IG (генерация TS / Zod / C#)
  • us-core — конкретный пример IG который мы пока не используем формально
  • formalize-fhir-profiles — наше решение писать ли свой IG — draft

Graph View

Backlinks