FHIR Annotation (data type)

Annotation — это FHIR data type (не самостоятельный resource), форма комментария: текст + кто/когда написал¹. Встраивается как поле note[] внутри ресурсов с заметками. Каждая запись в note[] имеет одинаковую структуру независимо от хост-ресурса.

Ресурсы, использующие Annotation через поле note[] (имя поля одинаковое везде, тип Annotation[]):

• заметка к наблюдению — Observation fhir-observation
• комментарий к диагнозу — Condition fhir-condition
• контекст реакции — AllergyIntolerance fhir-allergy-intolerance
• детали выполнения — Procedure fhir-procedure
• комментарий приёма — MedicationStatement fhir-medication-statement
• комментарий к плану — CarePlan fhir-careplan
• запрос на услугу — ServiceRequest (entity-page не создана)
• семейный анамнез — FamilyMemberHistory (entity-page не создана)
• и др.

Исключение: DiagnosticReport fhir-diagnostic-report не имеет note[] — для interpretation используется отдельное поле conclusion (string) + conclusionCode (CodeableConcept). Это исторический artifact FHIR R4; некоторые ресурсы пред-датируют унификацию через Annotation.

Два варианта — authorReference или authorString

Annotation.author[x] — это [[fhir-basics#Choice types ([x] суффикс)|choice type]]: значение задаётся одним из двух имён (не обоими сразу). Reference богаче — хранит версию софта, credentials, metadata через FHIR-объект. String проще — одна строка без модели.

// (1) Reference: ссылка на FHIR-ресурс
{
  "authorReference": { "reference": "Organization/bloodgpt-com" },
  "time": "2026-02-13T10:30:00Z",
  "text": "Параметр повышен — связано с приёмом пищи перед анализом"
}

// (2) String: просто имя
{
  "authorString": "Dr. Smith",
  "time": "2026-02-13T10:30:00Z",
  "text": "Recheck in 3 weeks"
}

Подробнее про [x]-суффикс как general FHIR pattern (и в каких других полях он встречается) — [[fhir-basics#Choice types ([x] суффикс)]].

Использование в BloodGPT

Когда мы добавляем AI-объяснение к Observation — мы не создаём отдельный ресурс, а заполняем note[] массив внутри той же Observation.

• Observation.note[] — AI-сгенерированный parameterDetails (объяснение параметра пациенту) → Annotation с text + authorReference → Organization/bloodgpt-com. Это legacy V2-decision и сейчас оспаривается — Ильдар считает что AI-объяснение параметра должно жить отдельным ресурсом (ClinicalImpression или подобный), а не комментарием внутри Observation. Аргументация и альтернативы — fhir-modeling-ai-content.
• Composition.author и CarePlan.author — это не Annotation, а отдельное поле типа Reference (тот же choice-type механизм author[x], но без обёртки Annotation). Семантика «кто автор всего ресурса», не «кто написал заметку внутри ресурса».

То есть Annotation = «комментарий внутри ресурса». Composition.author / CarePlan.author = «автор ресурса целиком» (другое поле, общий choice-type механизм).

Choice автора — [[domain/authorship-organization-not-device|authorReference → Organization/bloodgpt-com (не Device, не string)]]².

Связано

• fhir-basics — primer (Resource vs DataType, Choice types [x])
• fhir-observation — основной потребитель Annotation через note[]
• fhir-composition — author как Reference на верхнем уровне ресурса
• fhir-careplan — то же
• fhir-device — был кандидатом на authorReference target, superseded (см. authorship-organization-not-device)
• authorship-organization-not-device — actual choice

Источники

Сноски

1. HL7 R4 spec, «Annotation», accessed 2026-05-17, https://hl7.org/fhir/R4/datatypes.html#annotation — data type definition + field schema. ↩

2. Сессия ildar/871a7608, 2026-02-13 — обсуждение choice type для Annotation.author[x]; решено использовать authorReference → Organization, не Device, не plain string. ↩