Quartz 4

Категории внутри FHIR-ресурсов (Resource.category)

draft
Not verified

7 min read

Большинство клинических FHIR-ресурсов имеют поле category — для разделения подтипов внутри одного типа ресурса. Cardinality и type разные, не на всех ресурсах присутствует — но паттерн системный, штатный способ FHIR классифицировать данные, не custom extension.

Применимые use case’ы у нас: фильтрация в UI (panel «Vitals» vs panel «Lab»), routing в pipeline (lab vs vital-sign разная обработка), иконки в Timeline / medical-context page (один значок на категорию вместо одного на ресурс-тип), search-фильтр через ?category=....

Каноническая картина (FHIR R4)

Сводка — cardinality, тип поля, размер ValueSet’а.

РесурсCardinalityТипЗакрытость enumРазмер
Observation0..*CodeableConceptextensible9 кодов
DiagnosticReport0..*CodeableConceptexample (open)40+ кодов
Condition0..*CodeableConceptextensible2 кода R4 (US-Core добавляет 3-й)
MedicationStatement0..1CodeableConceptexample (open)4 кода
Procedure0..1CodeableConceptexample (open)SNOMED-based
AllergyIntolerance0..*code (примитив)closed4 кода — нельзя расширить
Immunization——n/aнет поля; классификация через vaccineCode
ServiceRequest0..*CodeableConceptexampleSNOMED-based
CarePlan0..*CodeableConceptexampleextensible
DocumentReference0..*CodeableConceptexampleLOINC document classes
Composition0..*CodeableConceptexampleextensible

Источник истины — конкретный resource page на https://hl7.org/fhir/R4/ (например observation.html#category).

Структурные нюансы

  • code vs CodeableConcept у AllergyIntolerance — поле примитивного типа code, нельзя добавить custom system, value привязан к фиксированному перечню FHIR из 4 значений. Если нужны более точные категории (lifestyle / drug-class) — придётся через extension или через code.coding[] основного поля substance, не через category.
  • 0..1 у MedicationStatement / Procedure — нельзя поставить две category одновременно (например, «outpatient + chronic»). Если нужно — расширяй coding[] внутри одной CodeableConcept.
  • type vs category у Composition / DocumentReference — type точная классификация (LOINC document code), category широкая (laboratory / note). Используются ВМЕСТЕ, не одно вместо другого. См. [[uploaded-document-types]].

Стандартные значения по ресурсам

Observation — 9 кодов

http://hl7.org/fhir/ValueSet/observation-category

  • laboratory — лаб-результаты
  • vital-signs — давление, пульс, частота дыхания, рост, вес, температура
  • imaging — наблюдения из imaging (X-ray, УЗИ, CT, MRI) — отдельно от DiagnosticReport
  • survey — опросники (Apgar, MoCA)
  • exam — физикальный осмотр клинициста
  • procedure — наблюдения из вмешательств (например intra-op vitals)
  • social-history — курение, алкоголь, occupation
  • therapy — non-interventional treatments (occupational/physical/radiation/medication therapy)
  • activity — физическая активность, fitness

Condition — 2 кода (R4)

http://hl7.org/fhir/ValueSet/condition-category

  • problem-list-item — хронический диагноз в problem list (ведётся во времени, может управляться разными practitioner’ами или patient)
  • encounter-diagnosis — point-in-time диагноз в context конкретного Encounter

US-Core extension добавляет третий — health-concern (concern юзера, не подтверждённый medically). В R4 ValueSet этого нет, появляется только в US-Core profile.

AllergyIntolerance — 4 кода (closed enum)

Поле code-типа (примитив), не CodeableConcept — нельзя custom-coding. Closed ValueSet.

  • food — пища
  • medication — препарат
  • environment — окружение (пыль, пыльца, латекс, металлы)
  • biologic — препарат биологического происхождения (vaccines, gene therapy, cellular therapy, mAb)

MedicationStatement — 4 кода

http://hl7.org/fhir/ValueSet/medication-statement-category

  • inpatient — в стационаре
  • outpatient — амбулаторно (приёмное, поликлиника, day surgery, doctor’s office)
  • community — дома (включая long-term care, hospice, nursing homes)
  • patientspecified — со слов пациента (OTC, что-то от другого провайдера)

DiagnosticReport — codesystem v2-0074, 40+ кодов

http://terminology.hl7.org/CodeSystem/v2-0074. Tree-style classification (Laboratory > Hematology > Blood Bank), не плоская таксономия. Топ-15 практически релевантных:

  • LAB — Laboratory (общее)
  • HM — Hematology
  • CH — Chemistry
  • MB — Microbiology
  • SR — Serology
  • IMM — Immunology
  • RAD — Radiology
  • CT — CAT Scan
  • RUS — Radiology Ultrasound
  • NMS — Nuclear Medicine Scan
  • EC — Electrocardiac (EKG)
  • SP — Surgical Pathology
  • PF — Pulmonary Function
  • PT — Physical Therapy
  • BLB — Blood Bank

Procedure — нет фиксированного ValueSet

Использует SNOMED CT, R4 spec даёт только примеры. Top-level concepts:

  • 387713003 — Surgical procedure
  • 103693007 — Diagnostic procedure
  • 24642003 — Psychiatry
  • 409063005 — Counselling
  • 409073007 — Education
  • 410606002 — Social service procedure
  • 46947000 — Chiropractic manipulation

Open-ended — допустимо взять любой релевантный SNOMED.

CarePlan — extensible

http://hl7.org/fhir/ValueSet/care-plan-category — open-ended. Содержит SNOMED 734163000 Care plan + open для custom (например HL7 assess-plan).

DocumentReference / Composition — type + category dual

Имеют оба поля одновременно:

  • type (singular, 1..1 для Composition) — точно что за документ (LOINC document class — 11502-2 Laboratory report, 11488-4 Consultation note)
  • category (multi, 0..*) — бизнес-bucket поверх (например LOINC 47039-3 Hospital Admission History)

Что мы пишем сейчас

Аудит builder’ов (май 2026, ветка v2-5-fhir). Полный список где category set’ится в коде:

РесурсСтандартный кодCustom параллельноГде код
Observation (lab из VLM)laboratorybloodgpt.com/CodeSystem/panel-categories (slug панели, e.g. «Биохимия»)apps/analysis-worker/src/inngest/functions/steps/save-fhir-resources.function.ts:299-310
Observation (lab + group, enrich)laboratorysame panel-categoriespackages/analysis-core/src/lib/fhir-observation-builders.ts:825+
Observation (narrative из LLM)enum 7 кодов R4—packages/analysis-core/src/services/narrative-to-fhir/fhir-builders/observation.ts:155
Observation (symptom narrative)exam hardcoded—narrative-to-fhir/fhir-builders/observation.ts:93
DiagnosticReportLAB hardcoded—3 места: save-fhir-resources, fhir-client.ts:990,1780, fhir-observation-builders.ts:619
Condition (narrative)problem-list-item hardcoded—narrative-to-fhir/fhir-builders/condition.ts:86-96
AllergyIntolerance (narrative)enum все 4 кода R4—narrative-to-fhir/fhir-builders/allergy-intolerance.ts:86
MedicationStatement❌ не set—gap
Procedure❌ не set—gap
CarePlan—bloodgpt.com/careplan-category code follow-up-recommendationspackages/analysis-core/src/lib/fhir-careplan-builder.ts:164-173
Composition (top-level)❌ не setsection codes — bloodgpt.com/step-categorypackages/analysis-core/src/lib/fhir-composition-builder.ts:170 (только section-codes, не resource-level)
Immunizationn/a (resource не emit’ится)—gap — narrative LLM extracts content_type=immunization, но builder для Immunization отсутствует

LLM-схемы что extracted из narrative (packages/analysis-core/src/schemas/extracted-medical-data.schema.ts):

  • ObservationCategoryEnum — ["laboratory", "vital-signs", "imaging", "procedure", "survey", "exam", "social-history"] (7 of 9 кодов R4 — therapy, activity опущены)
  • AllergyCategoryEnum — все 4 R4 кода (food / medication / environment / biologic)
  • Condition / MedicationStatement / Procedure — категория из LLM не extracted

Notable findings (за гранью category, но связано)

Condition default = problem-list-item

(Файл narrative-to-fhir/fhir-builders/condition.ts:77-95, явное rationale в комменте.)

«encounter-diagnosis semantically refers к Encounter ресурсу, а мы Encounter не создаём → reference incoherent. Все хроники (T2DM, asthma, hypothyroidism) → problem list. US-Core query Condition?category=problem-list-item найдёт их».

Грамотное coding decision уже принято — не сломать при изменениях.

AllergyIntolerance.verificationStatus default = unconfirmed

(Файл narrative-to-fhir/fhir-builders/allergy-intolerance.ts:33-47 + schema 67-77.)

Patient-reported «у меня в детстве была сыпь от пенициллина» не promoted в confirmed — это false-positive что приводит к suboptimal prescribing (Macy/Contreras 2014, JACI 133(3):790).

confirmed reserved для explicit clinical verification: «skin-prick positive», «IgE-confirmed», «allergist diagnosed», «documented anaphylaxis», «RAST positive». refuted — для «previously reported penicillin allergy ruled out via challenge test».

Это та же семантика что обсуждается для timeline source/confidence axes — когда decision-страница про timeline-page-design появится, ссылаться сюда.

SNOMED coder — недавний clinical-safety audit

В narrative-to-fhir/snomed-coder.ts Артур (май 2026) прошёл по lookup table с CSIRO Ontoserver $lookup (FHIR R4 terminology server, AU edition release 2026-04-30). Нашёл и пофиксил wrong-concept bugs — например 30242009 был для «hyperplastic polyp of colon» а в реальном SNOMED это «scarlet fever». Серьёзная clinical-safety работа, не косметика.

Гэпы для иконок Timeline

Чтобы на timeline можно было брать иконку из category для каждого ресурса:

GapЧто добавитьГде
MedicationStatement.categorycommunity или patientspecified (выбрать default — мы пишем со слов пациента, скорее всего patientspecified)narrative-to-fhir/fhir-builders/medication-statement.ts
Procedure.categorySNOMED broad (387713003 Surgical / 103693007 Diagnostic / 409063005 Counselling) — может из extracted-классификацииnarrative-to-fhir/fhir-builders/procedure.ts
Composition.category (top-level)например assess-plan (и параллельно сохранить custom step-category на section-codes)packages/analysis-core/src/lib/fhir-composition-builder.ts
CarePlan.category — custom systemзаменить на std assess-plan или add std parallel рядом с custompackages/analysis-core/src/lib/fhir-careplan-builder.ts:164
DiagnosticReport.category — только LABрасширить per document_type (RAD / IMG / EC) — связано с [[../product/uploaded-document-types-supported]]3 места в коде
Immunizationдобавить builder если в LLM extracted появятся immunizationsновый файл narrative-to-fhir/fhir-builders/immunization.ts

Связанные решения

  • [[../product/uploaded-document-types-supported]] — DocumentReference.category (broad) + DocumentReference.type (specific) могут параллельно жить
  • [[../domain/fhir-resource-origin-and-lifecycle]] — origin-tag через meta.tag ОРТОГОНАЛЕН category (origin = откуда данные пришли, category = что внутри)
  • [[../product/timeline-page-design]] — иконки timeline’а будут брать category значения отсюда (TBD не написано)
  • [[../domain/category-coverage]] — какие из gap’ов закрывать сейчас vs позже (TBD не написано)

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

  • Какие из gap’ов (MedicationStatement / Procedure / Composition / CarePlan std parallel) нужны для timeline v1, а какие можно оставить на v2?
  • US-Core extension health-concern для Condition — нужен ли он у нас (для self-reported concerns пациента) или хватает problem-list-item?
  • CarePlan custom system — оставить как есть (clear-cut «это наш AI»), заменить на std, или добавить std рядом?
  • Иконка-маппинг — отдельная UX-задача, нужен mapping table (laboratory → 🧪 / vital-signs → ❤️ / etc.). Не в scope этой страницы.

Связано

  • [[fhir-observation]] — главный потребитель category-разделения у нас
  • [[fhir-condition]] — наш default problem-list-item + rationale
  • [[fhir-allergy-intolerance]] — closed enum + verificationStatus default
  • [[fhir-medication-statement]] — gap (страница TBD)
  • [[fhir-procedure]] — gap (страница TBD)
  • [[fhir-diagnostic-report]] — только LAB используется (страница TBD)
  • [[fhir-document-reference]] — type + category dual classification
  • [[fhir-composition]] — gap top-level + custom step-category
  • [[fhir-careplan]] — custom system
  • [[patient-timeline-visualization]] — где категории применятся как иконки
  • [[uploaded-document-types]] — таксономия типов документов (для DocumentReference.type)

Источники

Источники: 1 2 3 4 5 6 7.

Сноски

  1. FHIR R4 Observation.category, accessed 2026-05-17, https://hl7.org/fhir/R4/observation.html#category. ↩

  2. FHIR R4 observation-category ValueSet, accessed 2026-05-17, https://hl7.org/fhir/R4/valueset-observation-category.html. ↩

  3. FHIR R4 condition-category ValueSet, accessed 2026-05-17, https://hl7.org/fhir/R4/valueset-condition-category.html. ↩

  4. FHIR R4 allergy-intolerance-category (closed), accessed 2026-05-17, https://hl7.org/fhir/R4/valueset-allergy-intolerance-category.html. ↩

  5. FHIR R4 medication-statement-category, accessed 2026-05-17, https://hl7.org/fhir/R4/valueset-medication-statement-category.html. ↩

  6. FHIR R4 v2-0074 (DiagnosticReport categories), accessed 2026-05-17, https://terminology.hl7.org/CodeSystem-v2-0074.html. ↩

  7. FHIR R4 care-plan-category, accessed 2026-05-17, https://hl7.org/fhir/R4/valueset-care-plan-category.html. ↩

Graph View

Backlinks