SubscriptionTopic
The subject of a FHIR notification channel: "patient-admitted", "observation-critical", "medication-administered". The subscription contract.
Purpose
SubscriptionTopic defines a publishable event on a FHIR server: data structure conveyed, frequency, triggers, available filters. A Subscription points to a SubscriptionTopic to subscribe. It is the FHIR equivalent of a queue subject or Kafka topic, with structured filter and payload profiles.
Key elements
| Field | Type | Cardinality | Role |
|---|---|---|---|
url | uri | 1..1 | Unique canonical URL. |
identifier | Identifier[] | 0..* | External identifiers. |
version | string | 0..1 | Version. |
name | string | 0..1 | Name. |
title | string | 0..1 | Title. |
status | code | 1..1 | `draft`, `active`, `retired`, `unknown`. |
date | dateTime | 0..1 | Date. |
description | markdown | 0..1 | Description. |
resourceTrigger | BackboneElement[] | 0..* | Triggers (create, delete, update). |
eventTrigger | BackboneElement[] | 0..* | Event triggers (SNOMED code, internal code). |
canFilterBy | BackboneElement[] | 0..* | Available filters. |
notificationShape | BackboneElement[] | 0..* | Payload shape. |
JSON example
{
"resourceType": "SubscriptionTopic",
"id": "example-admission",
"url": "https://example.org/fhir/SubscriptionTopic/admission-discharge",
"version": "1.0.0",
"name": "AdmissionDischargeTopic",
"title": "Admissions et sorties patient",
"status": "active",
"date": "2026-05-15",
"description": "Notifie sur création ou changement de statut d'un Encounter en mode admission ou discharge.",
"resourceTrigger": [{
"description": "Tout changement de statut Encounter",
"resource": "Encounter",
"supportedInteraction": ["create", "update"],
"queryCriteria": {
"current": "status=in-progress,finished"
}
}]
}Common pitfalls
- Non-unique canonical URL: collision with another Topic on the server.
- Neither resourceTrigger nor eventTrigger: empty Topic, no Subscription will attach.
- Malformed queryCriteria: subscribers receive events they did not want.
Related resources
- subscription — consumer subscription.
- subscriptionstatus — notification payload.
- messagedefinition — Messaging event model.
- eventdefinition — business trigger.