compatibility hints for topic-based subscription connectors

docs/modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md

@@ -8,45 +8,6 @@ description: FHIR Subscriptions Aidbox Topic-Based Subscriptions for real-time n
 This functionality is available in Aidbox versions 2409 and later and requires [FHIR Schema](../profiling-and-validation/fhir-schema-validator/) validation engine to be [enabled](../profiling-and-validation/fhir-schema-validator/).
 {% endhint %}
 
-{% hint style="warning" %}
-**Connector compatibility (Aidbox 2604+)**
-
-Starting from Aidbox **2604**, AidboxTopicDestination profile URLs were renamed and connector JARs must be built against a compatible Aidbox release.
-
-| Aidbox version | Profile URL form | Connector JAR |
-| --- | --- | --- |
-| ≥ 2604 | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-<nameProfile>` | `topic-destination-<name>` built against Aidbox 2604+ |
-| < 2604 | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-<kind>` (legacy) | connector JAR from the same Aidbox era |
-
-The kind segment differs: new form is camelCase with a `Profile` suffix (e.g. `clickHouseProfile`, `awssnsAtLeastOnceProfile`), legacy form is kebab-case (e.g. `clickhouse`, `aws-sns-at-least-once`). It is not a host-only substitution.
-
-Profile name mapping:
-
-| Kind | `<nameProfile>` (≥ 2604) | `<kind>` (< 2604) |
-| --- | --- | --- |
-| ClickHouse | `clickHouseProfile` | `clickhouse` |
-| ClickHouse at-least-once | `clickHouseAtLeastOnceProfile` | `clickhouse-at-least-once` |
-| BigQuery at-least-once | `bigQueryAtLeastOnceProfile` | `bigquery-at-least-once` |
-| Kafka best-effort | `kafkaBestEffortProfile` | `kafka-best-effort` |
-| Kafka at-least-once | `kafkaAtLeastOnceProfile` | `kafka-at-least-once` |
-| Kafka best-effort (mock) | `kafkaBestEffortMockProfile` | `kafka-best-effort-mock` |
-| Kafka at-least-once (mock) | `kafkaAtLeastOnceMockProfile` | `kafka-at-least-once-mock` |
-| Webhook at-least-once | `webhookAtLeastOnceProfile` | `webhook-at-least-once` |
-| GCP Pub/Sub at-least-once | `gcpPubSubAtLeastOnceProfile` | `gcp-pubsub-at-least-once` |
-| AWS EventBridge best-effort | `awsEventBridgeBestEffortProfile` | `aws-eventbridge-best-effort` |
-| AWS EventBridge at-least-once | `awsEventBridgeAtLeastOnceProfile` | `aws-eventbridge-at-least-once` |
-| AWS SNS best-effort | `awssnsBestEffortProfile` | `aws-sns-best-effort` |
-| AWS SNS at-least-once | `awssnsAtLeastOnceProfile` | `aws-sns-at-least-once` |
-| NATS Core best-effort | `natsCoreBestEffortProfile` | `nats-core-best-effort` |
-| NATS JetStream at-least-once | `natsJetStreamAtLeastOnceProfile` | `nats-jetstream-at-least-once` |
-| AMQP RabbitMQ 0-9-1 | `amqpRabbitMQ091Profile` | `amqp-rabbitmq-0-9-1` |
-| AMQP RabbitMQ 0-9-1 at-least-once | `amqpRabbitMQ091AtLeastOnceProfile` | `amqp-rabbitmq-0-9-1-at-least-once` |
-| AMQP 1-0 at-least-once | `amqp10AtLeastOnceProfile` | `amqp-1-0-at-least-once` |
-| FHIR native topic-based subscription | `fhirNativeTopicBasedSubscriptionProfile` | `fhir-native-topic-based-subscription` |
-
-Tutorials use the new (≥ 2604) URL form. For Aidbox **< 2604**, substitute both host and kind per the table. When upgrading across the 2604 boundary, redeploy the connector JAR — older JARs register profiles via a legacy path the new FAR-backed validator ignores.
-{% endhint %}
-
 ### Overview
 
 This feature enables dynamic subscriptions to changes in FHIR resources, allowing users/systems to receive notifications through [multiple channels](#currently-supported-channels).

docs/modules/topic-based-subscriptions/fhir-topic-based-subscriptions.md

@@ -12,7 +12,14 @@ This functionality requires [FHIR Schema](../profiling-and-validation/fhir-schem
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Profile URL |
+| --- | --- |
+| ≥ 2604 | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-fhirNativeTopicBasedSubscriptionProfile` |
+| < 2604 | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-fhir-native-topic-based-subscription` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap the `meta.profile` URL. The FHIR-native subscription destination ships with Aidbox core — no separate connector JAR.
 {% endhint %}
 
 ## Overview

docs/tutorials/subscriptions-tutorials/activemq-tutorial.md

@@ -5,7 +5,14 @@ description: Integrate Aidbox Topic-Based Subscriptions with ActiveMQ using AMQP
 # AidboxTopicSubscription ActiveMQ tutorial
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Connector JAR | Profile URL |
+| --- | --- | --- |
+| ≥ 2604 | `topic-destination-amqp-2604.0.jar` | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-amqp10AtLeastOnceProfile` |
+| < 2604 | `topic-destination-amqp-2509.4.jar` | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-amqp-1-0-at-least-once` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap both the JAR and the `meta.profile` URL. Redeploy the JAR when crossing the 2604 boundary — older JARs register profiles via a legacy path the new validator no longer honors.
 {% endhint %}
 
 ## Objectives
@@ -64,20 +71,20 @@ Both versions support AMQP 1.0 protocol, making them compatible with Aidbox's `a
 2.  Download **.jar** AMQP module file from [our bucket](https://storage.googleapis.com/aidbox-modules) and place it next to **docker-compose.yaml**.
 
     ```sh
-    curl -O https://storage.googleapis.com/aidbox-modules/topic-destination-amqp/topic-destination-amqp-2509.4.jar
+    curl -O https://storage.googleapis.com/aidbox-modules/topic-destination-amqp/topic-destination-amqp-2604.0.jar
     ```
 3.  Add jar module file to Aidbox:
 
     ```yaml
         volumes:
         # module jar to turn on AMQP support
-        - ./topic-destination-amqp-2509.4.jar:/topic-destination-amqp-2509.4.jar
+        - ./topic-destination-amqp-2604.0.jar:/topic-destination-amqp-2604.0.jar
     ```
 
     Set envs to import it on start:
 
     ```yaml
-       BOX_MODULE_JAR: "/topic-destination-amqp-2509.4.jar"
+       BOX_MODULE_JAR: "/topic-destination-amqp-2604.0.jar"
        BOX_MODULE_LOAD: io.healthsamurai.topic-destination.amqp.core
     ```
 4.  Start the services.

docs/tutorials/subscriptions-tutorials/aidboxtopicsubscription-nats-tutorial.md

@@ -5,7 +5,14 @@ description: Integrate Aidbox topic-based subscriptions with NATS and NATS JetSt
 # AidboxTopicSubscription NATS tutorial
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Connector JAR | Profile URL |
+| --- | --- | --- |
+| ≥ 2604 | `topic-destination-nats-2604.0.jar` | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-natsCoreBestEffortProfile`<br>`http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-natsJetStreamAtLeastOnceProfile` |
+| < 2604 | `topic-destination-nats-2602.1.jar` | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-nats-core-best-effort`<br>`http://aidbox.app/StructureDefinition/aidboxtopicdestination-nats-jetstream-at-least-once` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap both the JAR and the `meta.profile` URL. Redeploy the JAR when crossing the 2604 boundary — older JARs register profiles via a legacy path the new validator no longer honors.
 {% endhint %}
 
 ## Objectives

docs/tutorials/subscriptions-tutorials/aidboxtopicsubscription-sns-tutorial.md

@@ -11,7 +11,14 @@ This functionality is available starting from Aidbox version **2602**.
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Connector JAR | Profile URL |
+| --- | --- | --- |
+| ≥ 2604 | `topic-destination-sns-2604.0.jar` | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-awssnsBestEffortProfile`<br>`http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-awssnsAtLeastOnceProfile` |
+| < 2604 | `topic-destination-sns-2602.1.jar` | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-aws-sns-best-effort`<br>`http://aidbox.app/StructureDefinition/aidboxtopicdestination-aws-sns-at-least-once` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap both the JAR and the `meta.profile` URL. Redeploy the JAR when crossing the 2604 boundary — older JARs register profiles via a legacy path the new validator no longer honors.
 {% endhint %}
 
 ## Objectives

docs/tutorials/subscriptions-tutorials/aws-eventbridge-aidboxtopicdestination.md

@@ -11,7 +11,14 @@ This functionality is available starting from Aidbox version **2601**.
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Connector JAR | Profile URL |
+| --- | --- | --- |
+| ≥ 2604 | `topic-destination-aws-eventbridge-2604.0.jar` | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-awsEventBridgeBestEffortProfile`<br>`http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-awsEventBridgeAtLeastOnceProfile` |
+| < 2604 | `topic-destination-aws-eventbridge-2601.1.jar` | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-aws-eventbridge-best-effort`<br>`http://aidbox.app/StructureDefinition/aidboxtopicdestination-aws-eventbridge-at-least-once` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap both the JAR and the `meta.profile` URL. Redeploy the JAR when crossing the 2604 boundary — older JARs register profiles via a legacy path the new validator no longer honors.
 {% endhint %}
 
 ## Objectives

docs/tutorials/subscriptions-tutorials/bigquery-aidboxtopicdestination.md

@@ -9,7 +9,14 @@ This functionality is available starting from version 2603.
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Connector JAR | Profile URL |
+| --- | --- | --- |
+| ≥ 2604 | `topic-destination-bigquery-2604.0.jar` | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-bigQueryAtLeastOnceProfile` |
+| < 2604 | `topic-destination-bigquery-2603.1.jar` | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-bigquery-at-least-once` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap both the JAR and the `meta.profile` URL. Redeploy the JAR when crossing the 2604 boundary — older JARs register profiles via a legacy path the new validator no longer honors.
 {% endhint %}
 
 ## Overview

docs/tutorials/subscriptions-tutorials/clickhouse-aidboxtopicdestination.md

@@ -9,7 +9,14 @@ This functionality is available starting from version 2507 and requires [FHIR Sc
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Connector JAR | Profile URL |
+| --- | --- | --- |
+| ≥ 2604 | `topic-destination-clickhouse-2604.0.jar` | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-clickHouseProfile`<br>`http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-clickHouseAtLeastOnceProfile` |
+| < 2604 | `topic-destination-clickhouse-2512.2.jar` | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-clickhouse`<br>`http://aidbox.app/StructureDefinition/aidboxtopicdestination-clickhouse-at-least-once` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap both the JAR and the `meta.profile` URL. Redeploy the JAR when crossing the 2604 boundary — older JARs register profiles via a legacy path the new validator no longer honors.
 {% endhint %}
 
 ## Overview

docs/tutorials/subscriptions-tutorials/fhir-subscription-r4-backport.md

@@ -9,7 +9,14 @@ This functionality is available in Aidbox versions 2512 and later and requires [
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Profile URL |
+| --- | --- |
+| ≥ 2604 | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-fhirNativeTopicBasedSubscriptionProfile` |
+| < 2604 | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-fhir-native-topic-based-subscription` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap the `meta.profile` URL. The FHIR-native subscription destination ships with Aidbox core — no separate connector JAR.
 {% endhint %}
 
 For concepts, supported fields, and configuration details, see [FHIR Topic-Based Subscriptions](../../modules/topic-based-subscriptions/fhir-topic-based-subscriptions.md).

docs/tutorials/subscriptions-tutorials/fhir-subscription-r4b-backport.md

@@ -9,7 +9,14 @@ This functionality is available in Aidbox versions 2601 and later and requires [
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Profile URL |
+| --- | --- |
+| ≥ 2604 | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-fhirNativeTopicBasedSubscriptionProfile` |
+| < 2604 | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-fhir-native-topic-based-subscription` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap the `meta.profile` URL. The FHIR-native subscription destination ships with Aidbox core — no separate connector JAR.
 {% endhint %}
 
 For concepts, supported fields, and configuration details, see [FHIR Topic-Based Subscriptions](../../modules/topic-based-subscriptions/fhir-topic-based-subscriptions.md).

docs/tutorials/subscriptions-tutorials/fhir-subscription-r5.md

@@ -9,7 +9,14 @@ This functionality is available in Aidbox versions 2601 and later and requires [
 {% endhint %}
 
 {% hint style="warning" %}
-**Aidbox 2604+ compatibility:** AidboxTopicDestination profile URLs were renamed — both the host (`aidbox.app` → `health-samurai.io/fhir/core`) and the kind segment (kebab-case → camelCase with a `Profile` suffix). Examples below use the new URL. For Aidbox **< 2604**, look up the legacy URL in the [connector compatibility table](../../modules/topic-based-subscriptions/aidbox-topic-based-subscriptions.md). When upgrading Aidbox across the 2604 boundary, redeploy the connector JAR against an Aidbox 2604+ release — older connector JARs register profiles through a legacy path the new validator no longer honors.
+**Aidbox version compatibility**
+
+| Aidbox | Profile URL |
+| --- | --- |
+| ≥ 2604 | `http://health-samurai.io/fhir/core/StructureDefinition/aidboxtopicdestination-fhirNativeTopicBasedSubscriptionProfile` |
+| < 2604 | `http://aidbox.app/StructureDefinition/aidboxtopicdestination-fhir-native-topic-based-subscription` |
+
+Examples below use the ≥ 2604 form. On older Aidbox, swap the `meta.profile` URL. The FHIR-native subscription destination ships with Aidbox core — no separate connector JAR.
 {% endhint %}
 
 For concepts, supported fields, and configuration details, see [FHIR Topic-Based Subscriptions](../../modules/topic-based-subscriptions/fhir-topic-based-subscriptions.md).