FHIR-ресурсы делятся на два класса: клинические (Patient, Observation, Condition, и т.д. — про пациента) и conformance (метаресурсы — про устройство самой системы). Conformance-ресурсы описывают что система обязана уметь и как должны быть устроены клинические ресурсы. Это самоописательный механизм FHIR — стандарт сам себя описывает в собственных же ресурсах.
Где живёт в данных
- В коде BloodGPT — нигде формально не определены. У нас vanilla R4, conformance-ресурсы из base spec используются неявно (через
@types/fhir), своих не создаём. - На Google Healthcare API — лежат как обычные ресурсы в отдельных endpoint’ах (
/StructureDefinition/,/ValueSet/,/CapabilityStatement, и т.д.). FHIR-сервер раздаёт их по запросу — клиент может узнать «что ты умеешь» черезGET /metadata(CapabilityStatement). - В индустрии — IG’и публикуют их пачкой как часть Implementation Guide (HTML + JSON + NPM package).
Состав семейства
| Ресурс | Что описывает | Пример |
|---|---|---|
| StructureDefinition | shape конкретного ресурса (cardinality, типы полей, fixed values, slicing, extensions) | USCorePatient — какие identifier’ы обязательны, must-support fields, value bindings |
| ValueSet | набор разрешённых кодов (выборка из CodeSystem’ов) | BodyHeightLoincCodes — все LOINC-коды для body height |
| CodeSystem | сам словарь кодов с определениями | LOINC (внешний — Regenstrief), bloodgpt.com/CodeSystem/section-type (свой) |
| CapabilityStatement | что FHIR-сервер умеет (resources, operations, search params, security) | Google Healthcare API exposes through GET /metadata |
| OperationDefinition | кастомная операция поверх REST | $everything (вытащить все данные пациента), $validate (валидировать ресурс) |
| SearchParameter | как искать (имя параметра, на что мапится в ресурсе, тип) | Patient?birthdate=1980-01-01 → birthdate search-param |
| ImplementationGuide | контейнер, связывающий все остальные conformance-ресурсы в одну поставку | hl7.fhir.us.core — IG со всеми SDs / VSs / SearchParameters для US-рынка |
StructureDefinition — центральный ресурс семейства
Большинство практической работы с conformance-ресурсами это про StructureDefinition. Из него рождаются и FHIR profiles (constraint поверх базы), и extensions (тоже StructureDefinition, просто с type: Extension), и базовые типы R4 — все resource definitions в самом FHIR-стандарте описаны через SD.
Один SD — это машино-читаемое определение одного артефакта:
- Один профиль
BloodGPTComposition— один SD - Один extension
requires-doctor-preparation— отдельный SD - Базовый ресурс
Patient— отдельный SD (поставляется HL7)
См. fhir-profiling для того как через SD накладывают constraints на ресурсы.
ValueSet vs CodeSystem — частая путаница
Два разных артефакта, легко смешать:
- CodeSystem — это сам словарь с определениями кодов.
LOINC— это CodeSystem.SNOMED CT— это CodeSystem.bloodgpt.com/CodeSystem/section-type(наш, с кодамиtest-overview,panel-overviews,trends) — это CodeSystem. - ValueSet — это выборка конкретных кодов из одного или нескольких CodeSystem’ов под конкретный use case. Например, ValueSet «коды для observation-category» содержит 9 конкретных кодов из CodeSystem’а
terminology.hl7.org/CodeSystem/observation-category.
Один CodeSystem — миллионы кодов (LOINC = ~95k кодов). Один ValueSet — обычно от единиц до сотен. Profile в SD ссылается на ValueSet через binding, не на CodeSystem напрямую.
CapabilityStatement — declarative API spec
CapabilityStatement объявляет «вот этот FHIR-сервер поддерживает Patient/Observation/Condition; для Patient — read, search, create; search-параметры: identifier, birthdate, name». Клиент может прочитать его через GET /metadata (стандартный endpoint в каждом FHIR-сервере) и программно понять что доступно без human-readable docs.
У Google Healthcare API CapabilityStatement генерируется автоматически. У HAPI / Medplum — тоже. Кастомизировать обычно не приходится, но если сервер expose’ит OperationDefinitions / custom SearchParameters — они тоже там появятся.
ImplementationGuide — packaging для всего вышеперечисленного
ImplementationGuide — мета-ресурс который связывает набор SDs + ValueSets + CodeSystems + CapabilityStatement + OperationDefinitions + markdown-страниц в один пакет. Это то, что публикуется на simplifier.net, что устанавливается через npm install hl7.fhir.us.core, что отдельно билдится в HTML-сайт через IG Publisher. Deep-dive — fhir-implementation-guide.
Чем отличается от клинических ресурсов
| Аспект | Клинические (Patient, Observation, …) | Conformance (SD, ValueSet, …) |
|---|---|---|
| Содержание | Данные о пациенте | Описание системы / spec |
| Источник | Создаются приложением (write при загрузке анализа) | Создаются один раз при дизайне (или приходят из IG dependency) |
| Жизненный цикл | Меняются часто, накапливаются | Стабильны, версионируются как код |
| PHI | Содержат PHI (HIPAA-protected) | Не содержат PHI |
| Где хранить | FHIR-store с tenant изоляцией | Может быть отдельный store / packaged в коде / зависимость от IG |
| Кто пишет | Builder-код / pipeline | Архитектор / spec-команда |
Эта разделимость важна — кастомные conformance-ресурсы можно публиковать как открытый IG (например hl7.fhir.us.core), даже если клинические данные строго PHI.
Наше текущее состояние
- Не пишем своих SDs — vanilla R4 base SD’ов хватает (см. zero-extensions-fhir почему).
- Используем base ValueSets (например,
observation-category9-кодов R4) — описано в fhir-resource-categories. - Используем кастомные CodeSystem’ы (
bloodgpt.com/CodeSystem/section-typeдля секций нашего Composition,bloodgpt.com/CodeSystem/panel-categoriesдля slug’ов панелей). Это не extensions — это новые наборы кодов в стандартных полях. meta.profileв наших ресурсах пуст — не декларируем conformance.- Кастомных OperationDefinitions нет (используем стандартный
$everythingGoogle Healthcare API). - Если решим формализовать профайлинг — нужно будет начать с SDs и собрать собственный IG. Шаг описан на formalize-fhir-profiles.
Открытые вопросы
- Если решим публиковать собственный IG для downstream партнёров — какой набор conformance-ресурсов туда войдёт сразу: только SDs наших ресурсов, или также SearchParameter’ы (если у нас есть кастомные)?
- Куда выкладывать IG —
simplifier.net(публичный hub), собственный домен (build.bloodgpt.com/ig/), GitHub Pages?
Связано
- fhir-basics — базовые понятия FHIR (resource, reference, bundle), фундамент для понимания где conformance-resources вписываются
- fhir-profiling — основное практическое применение StructureDefinition (constraint поверх базы)
- fsh — DSL для написания StructureDefinition / ValueSet / CodeSystem human-readable способом
- fhir-implementation-guide — packaging conformance-resources в одну поставку
- fhir-code-generation — извлечение типов / валидаторов из SDs
- fhir-terminology-service — отдельный сервис для CodeSystem / ValueSet expand / validate операций
- formalize-fhir-profiles — наше решение писать ли свои conformance-resources — draft
- extension-url-conventions — URL convention для собственных extensions / SDs — draft
- zero-extensions-fhir — наше текущее решение жить без своих SDs — active