RFC: DSC Notification Paths

[herostrat]

Summary V3 (Updated to incorporate comments/findings from @panaaj and @TwoCanPlugIn )

Summary

Introduce a unified notification path structure based on maritime safety categories (distress, urgency, safety) that applies consistently across all vessel contexts. This replaces the current flat top-level notification names with a categorized hierarchy and enables transport-agnostic handling of alerts from DSC, AIS Safety Messages, and future sources.

Related issues

• VHF DSC Calls #209 — VHF DSC Calls (2016, @tkurki): Requested explicit schema handling for incoming VHF DSC calls. PGN 129808 was identified as the relevant N2K message. @timmathews noted that DSC calls should create vessel entries and generate alerts.
• Add data attribute to Alarm object used in Notification messages #655 — Add data attribute to Alarm object (2023, @panaaj): Proposes an optional data attribute for structured alarm data (e.g. MOB position). The notifications.mob.<MMSI> pattern used by @bergie in signalk-mob-notifier demonstrates real-world need for per-source notification keying.
• Examples for alarm notifications do not reflect the specification #668 — Examples for alarm notifications do not reflect the specification (2025, @ArjenR): Reports that the spec says notifications.mob.<key> but examples show notifications.mob without a key, causing incompatibility between FreeboardSK and KIP.
• DSC Distress Alerts nmea0183-signalk#217 — DSC Distress Alerts (2022, @TwoCanPlugIn): Reports that DSC/DSE parsing is broken. Comprehensive ITU/NMEA documentation for DSC field parsing was provided. As of September 2025, users still report inability to generate Signal K paths from DSC sentences.
• Add Basic support for DSC Position and Distress Sentences nmea0183-signalk#66 — Add Basic support for DSC Position and Distress Sentences (2016, @ph1l): The original DSC codec. Notably, this implementation already writes to the vessel context of the calling MMSI, not vessels.self.

Motivation

The ambiguity problem

The current specification defines 10 flat well-known notification paths (notifications.mob, notifications.fire, etc.) without distinguishing what kind of condition they represent or whose vessel they describe. A notifications.fire could mean:

• An onboard fire sensor detected fire on this vessel (life-threatening emergency)
• A DSC distress relay was received reporting fire on another vessel (informational)
• An NMEA ALR alarm from a connected device

These are fundamentally different situations requiring different responses.

The asymmetry problem

Signal K already stores received data from other vessels under their own context — AIS position from vessel 211457160 goes to vessels.211457160.navigation.position, not to vessels.self. Notifications should follow the same principle: a DSC distress from vessel 211457160 belongs under vessels.211457160.notifications.*, not under vessels.self.notifications.*.

But if external alerts use a categorized structure (notifications.distress.fire) while own-vessel alerts use a flat structure (notifications.fire), the notification tree is inconsistent across vessel contexts. There is no reason for this asymmetry other than backwards compatibility.

Maritime safety categories are universal

The categories distress, urgency, and safety are not DSC-specific — they are fundamental maritime safety categories defined by SOLAS and ITU, used across all maritime communication systems:

Category	Severity	Description	Alarm State
Distress	Highest	Life-threatening emergency (fire, sinking, MOB...)	emergency
Urgency	High	Requires immediate attention, not life-threatening	alarm
Safety	Medium	Navigational or meteorological warning	warn

These categories apply regardless of the source: a fire is a distress condition whether detected by an onboard sensor, received via DSC, reported through AIS, or relayed over LoRa. The transport is metadata ($source), not part of the path.

Current implementation issues

The nmea0183-signalk DSC parser (see #217, #66):

1. Only distress calls (category 12) generate notifications — urgency (10) and safety (08) are ignored
2. Notification values are incomplete — missing the required state and method fields
3. Parser is broken — as of 2025, DSC/DSE sentences fail to generate Signal K nodes at all
4. Already uses vessel context — the existing DSC codec writes to the calling vessel's MMSI context, not vessels.self

Proposal

Unified notification categories

Replace the flat top-level notification names with categorized branches that apply identically to all vessel contexts — own vessel (self) and others:

vessels.{any}.notifications.distress.*    — Life-threatening emergencies
vessels.{any}.notifications.urgency.*     — Urgent, non-life-threatening
vessels.{any}.notifications.safety.*      — Navigational/meteorological warnings

The path expresses what the condition is. The vessel context expresses whose vessel is affected. The $source field expresses how the information was received (DSC, AIS, onboard sensor, NMEA ALR, LoRa, etc.).

Distress sub-paths

Distress notifications use sub-paths corresponding to the ITU nature-of-distress codes:

notifications.distress.fire           — Fire/Explosion (code 00)
notifications.distress.flooding       — Flooding (code 01)
notifications.distress.collision      — Collision (code 02)
notifications.distress.grounding      — Grounding (code 03)
notifications.distress.listing        — Listing/Capsizing (code 04)
notifications.distress.sinking        — Sinking (code 05)
notifications.distress.adrift         — Adrift (code 06)
notifications.distress.undesignated   — Undesignated (code 07)
notifications.distress.abandon        — Abandon ship (code 08)
notifications.distress.piracy         — Piracy/Armed attack (code 09)
notifications.distress.mob            — Man overboard (code 10)
notifications.distress.epirb          — EPIRB emission (code 12)

Urgency and safety use descriptive sub-paths:

notifications.urgency.{description}
notifications.safety.{description}

Full path examples

Scenario	Path	Context	Source
Own vessel fire alarm (onboard sensor)	notifications.distress.fire	vessels.self	onboard sensor
Own vessel MOB button pressed	notifications.distress.mob	vessels.self	manual input
DSC Distress: fire from MMSI 211457160	notifications.distress.fire	vessels.urn:mrn:imo:mmsi:211457160	nmea0183.DSC
DSC Distress Relay: fire, orig. vessel 211457160	notifications.distress.fire	vessels.urn:mrn:imo:mmsi:211457160	nmea0183.DSC
DSC Urgency from MMSI 305000001	notifications.urgency.medicalAssistance	vessels.urn:mrn:imo:mmsi:305000001	nmea0183.DSC
AIS Safety Broadcast from MMSI 002111240	notifications.safety.broadcast	vessels.urn:mrn:imo:mmsi:002111240	nmea0183.VDM
AIS Addressed Safety Msg to own vessel	notifications.safety.addressed	vessels.urn:mrn:imo:mmsi:002111240	nmea0183.VDM
NMEA ALR depth alarm on own vessel	notifications.safety.depth	vessels.self	nmea0183.ALR
Anchor drag alarm (zone-based)	notifications.navigation.anchor.currentRadius	vessels.self	zone monitor

Note: zone-based operational alarms (anchor, depth via meta.zones, etc.) continue to use the existing mirrored-path convention (notifications.navigation.anchor.currentRadius). The distress/urgency/safety branches are for categorical emergency/alert conditions, not for zone-derived alarms.

Notification value format

All notifications must include the required fields per the existing spec:

{
  "value": {
    "message": "Distress: Fire/Explosion",
    "state": "emergency",
    "method": ["visual", "sound"]
  },
  "timestamp": "2024-01-15T14:30:00Z",
  "$source": "nmea0183.DSC"
}

Recommended state values per category:

• Distress: "emergency"
• Urgency: "alarm"
• Safety: "warn"

Delta examples

Own vessel — fire detected by onboard sensor:

{
  "context": "vessels.self",
  "updates": [{
    "source": { "label": "fire-detector", "type": "signalk" },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.distress.fire",
      "value": {
        "message": "Fire detected in engine room",
        "state": "emergency",
        "method": ["visual", "sound"]
      }
    }]
  }]
}

DSC Distress — fire from another vessel:

{
  "context": "vessels.urn:mrn:imo:mmsi:211457160",
  "updates": [{
    "source": {
      "label": "nmea0183",
      "type": "NMEA0183",
      "talker": "",
      "sentence": "DSC"
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.distress.fire",
      "value": {
        "message": "Distress: Fire/Explosion at 54.3000N, 10.5000E",
        "state": "emergency",
        "method": ["visual", "sound"]
      }
    }]
  }]
}

AIS Safety Broadcast:

{
  "context": "vessels.urn:mrn:imo:mmsi:002111240",
  "updates": [{
    "source": {
      "label": "nmea0183",
      "type": "NMEA0183",
      "talker": "AI",
      "sentence": "VDM"
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.safety.broadcast",
      "value": {
        "message": "Uncharted rock reported at 54.12N 010.34E",
        "state": "warn",
        "method": ["visual"]
      }
    }]
  }]
}

DSC Urgency call:

{
  "context": "vessels.urn:mrn:imo:mmsi:305000001",
  "updates": [{
    "source": {
      "label": "nmea0183",
      "type": "NMEA0183",
      "talker": "",
      "sentence": "DSC"
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.urgency.medicalAssistance",
      "value": {
        "message": "Urgency: Medical assistance required",
        "state": "alarm",
        "method": ["visual", "sound"]
      }
    }]
  }]
}

Routine calls (category 00)

Routine DSC calls do not generate notifications. They represent normal radio call requests and only update vessel position data if available.

DSC Distress vs. Distress Relay

A DSC Distress call (Format Specifier 12) is sent directly by the vessel in distress — the Category field is empty because distress is implied. A DSC Distress Relay (Format Specifier 16/All Ships, Category 12) is retransmitted by a third vessel (or coast station). Both cases produce the same Signal K path under the context of the vessel in distress. The distinction is captured in $source and is a parser-level concern, not a path-level concern.

The vessel-context model handles relays cleanly: regardless of whether a distress call is received directly or via one or more relays, it produces a single entry under the distressed vessel's context. If the same distress is received multiple times (direct call, then coast station relay, then another vessel's relay), each reception updates the same path with a new timestamp and $source. Signal K's native multi-source support means all sources are preserved, while the notification remains a single entry — no duplicates, no overwriting confusion.

Reception	Path	Context	$source
Direct from vessel A	notifications.distress.fire	vessels.urn:mrn:imo:mmsi:211457160	nmea0183.DSC
Relayed by coast station	notifications.distress.fire	vessels.urn:mrn:imo:mmsi:211457160	nmea0183.DSC
Via AIS Safety Broadcast	notifications.distress.fire	vessels.urn:mrn:imo:mmsi:211457160	nmea0183.VDM

The alarm manager triggers on the first reception. Subsequent receptions confirm the distress but do not raise additional alarms.

Notification Manager integration

Signal K Server's recently released Notifications API already provides the infrastructure this RFC requires. The API introduces an Input Handler that intercepts all incoming deltas whose path starts with notifications and routes them to a centralized Notification Manager. The Notification Manager enriches notifications with a unique id and a status object before emitting them to clients.

This pipeline works naturally with the unified model: a DSC distress delta with context vessels.urn:mrn:imo:mmsi:211457160 and path notifications.distress.fire has a path starting with notifications, so the Input Handler routes it to the Notification Manager like any other notification.

Alarm lifecycle for distress/urgency/safety

The Notifications API's status attributes map directly to the semantics of received external alerts:

Attribute	Distress (emergency)	Urgency (alarm)	Safety (warn)
canSilence	false (API already enforces: emergency cannot be silenced)	true	true
canAcknowledge	true (operator confirms awareness)	true	true
canClear	false (API already enforces: external notifications cannot be cleared)	false	false

This means the Notification Manager already handles the two critical constraints for received alerts: distress notifications cannot be silenced, and externally received notifications cannot be cleared by the operator (the condition exists on another vessel).

Cross-vessel notification awareness

Storing notifications under each vessel's own context means the Notification Manager must process notifications from all vessel contexts, not just vessels.self. Since the Input Handler already intercepts based on path prefix (notifications), this requires extending it to trigger operator alerts (visual/sound) for state: emergency or state: alarm notifications regardless of which vessel context they belong to.

This makes the alarm system severity-aware and transport-agnostic: a state: emergency notification triggers the alarm whether it originates from an onboard sensor, a DSC call, an AIS Safety Message, or a future LoRa source. The path tells the operator what happened, the vessel context tells them who is affected, $source tells them how the information was received.

Schema changes

New dscBranch definition

The existing notificationBranch definition uses a negative-lookahead regex that excludes the well-known names (mob, fire, sinking, etc.) at all nesting levels. This means notifications.distress.fire would be rejected — fire is blocked by the regex even inside distress.

A new dscBranch definition in notifications.json explicitly lists the nature-of-distress names as properties (allowing fire, mob, etc. as sub-paths) and also permits arbitrary additional sub-paths via patternProperties.

Files modified

1. schemas/groups/notifications.json:
   • Add distress, urgency, safety to the negative-lookahead regex in notificationBranch
   • Add new dscBranch definition with well-known nature-of-distress properties plus undesignated and epirb
2. schemas/vessel.json — Add distress, urgency, safety as well-known properties referencing dscBranch, update the regex
3. schemas/sar.json — Same as vessel.json
4. schemas/aircraft.json — Add properties block with distress, urgency, safety referencing dscBranch, update the regex
5. schemas/aton.json — Same as aircraft.json
6. mdbook/src/notifications.md — Document the unified model and DSC semantics

Backward compatibility

Non-breaking additions

The distress, urgency, and safety branches are new well-known names. The existing notificationBranch pattern already allows arbitrary nesting, so paths like notifications.distress.fire are valid today under the generic pattern. This RFC formalizes them as explicit schema properties.

Deprecation of flat top-level names

The existing flat paths (notifications.fire, notifications.mob, etc.) become deprecated in favour of their categorized equivalents (notifications.distress.fire, notifications.distress.mob, etc.). They should remain valid in the schema during a transition period but should no longer be used by new implementations.

The notifications.nmea.* path is currently used by n2k-signalk for NMEA2000 alarm PGNs (e.g. notifications.nmea.alarm.navigational.20.8196). This is a transport-based path — the nmea segment identifies how the alarm arrived, not what it describes. In the unified model, the same alarm would go to a category-based path (e.g. notifications.safety.navigation) with $source identifying the N2K origin. The existing notifications.nmea.* paths should remain valid during the transition period and continue to be processed by the Notification Manager.

Migration path

1. New parser implementations write to notifications.distress.* / notifications.urgency.* / notifications.safety.* under the appropriate vessel context
2. Existing top-level names remain valid but are marked deprecated in the spec documentation
3. Server alarm managers are extended to watch vessels.*.notifications.distress.* and vessels.*.notifications.urgency.*
4. A future spec version may remove the flat top-level names

Interaction with other proposals

#655 — data attribute for alarm objects

This RFC is complementary. The data attribute proposal would allow structured fields (position, MMSI) in the notification value, while this RFC addresses path structure and vessel context. Both can be adopted independently:

• Without data attribute: details go in the message string
• With data attribute: { "message": "Distress: Fire", "state": "emergency", "method": ["visual", "sound"], "data": { "position": { "latitude": 54.3, "longitude": 10.5 } } }

#668 — Notification path structure

The spec says notifications.mob.* but examples show notifications.mob. This RFC resolves the ambiguity: notifications.distress.mob is the leaf notification, and multiple concurrent MOBs from different vessels naturally exist as separate entries under different vessel contexts.

#378 — Notification Acknowledgements

The Notifications API already implements acknowledgement and silence actions via REST endpoints (/signalk/v2/api/notifications/{id}/acknowledge, /silence). The unified model is fully compatible: all notifications follow the same structure regardless of source, and the status attributes correctly restrict actions for external emergency notifications (cannot silence, cannot clear).

Notifications API (Signal K Server)

The recently released Notifications API introduces a Notification Manager with an Input Handler that intercepts all notification deltas. This RFC builds on that infrastructure rather than replacing it. The Notification Manager's id and status enrichment, action endpoints, and NMEA2000 alert handling all work with the categorized paths proposed here. The planned "raising specified alarms i.e. MOB" feature in the API's target state aligns with the well-known distress sub-paths (notifications.distress.mob, notifications.distress.fire, etc.).

Open questions

1. Structured data: Should the notification value object be extended with optional fields (position, nature-of-distress code) beyond the message string? Or should this be deferred to the data attribute proposal (Add data attribute to Alarm object used in Notification messages #655)? Currently, position and details are embedded in the human-readable message string. A UI that wants to plot the distress position on a chart would need to parse that string. A structured data object would make this machine-readable, but increases the scope of this RFC.

2. Cross-vessel notification awareness: The Notifications API's Input Handler currently intercepts notification deltas for processing by the Notification Manager. Should the Notification Manager be extended to trigger operator alerts for state: emergency and state: alarm notifications across all vessel contexts, not just vessels.self? This is the key enabler for the unified model — without it, received distress calls would be stored correctly but not raise alarms.

Previous Versions

Old/Original RFC

## Summary

Add well-known notification paths for Digital Selective Calling (DSC) categories under notifications.distress.*, notifications.urgency.*, and notifications.safety.* to separate externally received DSC alerts from own-vessel alarm conditions.

Related issues

This RFC addresses several open issues across the Signal K ecosystem:

• VHF DSC Calls #209 — VHF DSC Calls (2016, @tkurki): Requested explicit schema handling for incoming VHF DSC calls. PGN 129808 was identified as the relevant N2K message. @timmathews noted that DSC calls should create vessel entries and generate alerts. This RFC provides the notification path structure that was missing.
• Add data attribute to Alarm object used in Notification messages #655 — Add data attribute to Alarm object (2023, @panaaj): Proposes an optional data attribute for structured alarm data (e.g. MOB position). The notifications.mob.<MMSI> pattern used by @bergie in signalk-mob-notifier demonstrates real-world need for per-source notification keying. This RFC's notifications.distress.mob path is compatible with this approach (e.g. notifications.distress.mob.<MMSI> for multiple concurrent MOBs).
• Examples for alarm notifications do not reflect the specification #668 — Examples for alarm notifications do not reflect the specification (2025, @ArjenR): Reports that the spec says notifications.mob.<key> but examples show notifications.mob without a key, causing incompatibility between FreeboardSK and KIP. This RFC clarifies the path semantics and provides consistent examples.
• DSC Distress Alerts nmea0183-signalk#217 — DSC Distress Alerts (2022, @TwoCanPlugIn): Reports that DSC/DSE parsing is broken. @TwoCanPlugIn provided comprehensive ITU/NMEA documentation for DSC field parsing. As of September 2025, users still report inability to generate Signal K paths from DSC sentences. This RFC provides the target paths that the parser should produce.
• Add Basic support for DSC Position and Distress Sentences nmea0183-signalk#66 — Add Basic support for DSC Position and Distress Sentences (2016, @ph1l): The original DSC codec that was merged. This is the implementation that currently writes to the top-level notification paths without state/method fields.

Motivation

The current Signal K specification defines 10 well-known notification paths for emergencies:

• notifications.mob, notifications.fire, notifications.sinking, notifications.flooding
• notifications.collision, notifications.grounding, notifications.listing, notifications.adrift
• notifications.piracy, notifications.abandon

These paths are used for own-vessel conditions (e.g. an onboard fire sensor triggers notifications.fire). However, the same paths are also used by DSC implementations (e.g. signalk-parser-nmea0183) for distress calls received from other vessels.

This creates ambiguity: a notifications.fire could mean "my ship is on fire" (onboard sensor) or "I received a DSC distress relay reporting fire on another vessel". These are fundamentally different situations requiring different responses.

Current DSC implementation issues

Looking at the nmea0183-signalk DSC parser (see nmea0183-signalk#217, #66):

1. Only distress calls (category 12) generate notifications — urgency (10) and safety (08) are ignored
2. Notification values are incomplete — they contain a message but are missing the required state and method fields per the spec
3. Path collision — DSC distress relays from other vessels use the same top-level paths as own-vessel alarms
4. Parser is broken — As of 2025, DSC/DSE sentences fail to generate Signal K nodes at all (nmea0183-signalk#217)

DSC categories and their semantics

Category	Name	Description	Alarm State
12	Distress	Life-threatening emergency (fire, sinking, MOB...)	emergency
10	Urgency	Requires immediate attention, not life-threatening	alarm
08	Safety	Navigational or meteorological warning	warn
00	Routine	Normal radio call request	n/a

Nature of distress codes (category 12 only)

Code	Nature	Proposed path suffix
00	Fire/Explosion	fire
01	Flooding	flooding
02	Collision	collision
03	Grounding	grounding
04	Listing/Capsizing	listing
05	Sinking	sinking
06	Adrift	adrift
07	Undesignated	undesignated
08	Abandon ship	abandon
09	Piracy	piracy
10	Man overboard	mob
12	EPIRB emission	epirb

Proposal

New well-known notification branches

Add three new well-known notification branches:

Path	Type	Description
notifications.distress.*	branch	Distress notifications received via DSC (category 12)
notifications.urgency.*	branch	Urgency notifications received via DSC (category 10)
notifications.safety.*	branch	Safety notifications received via DSC (category 08)

Path structure

Distress notifications use sub-paths matching the nature of distress:

notifications.distress.fire        — Fire/Explosion
notifications.distress.flooding    — Flooding
notifications.distress.collision   — Collision
notifications.distress.grounding   — Grounding
notifications.distress.listing     — Listing/Capsizing
notifications.distress.sinking     — Sinking
notifications.distress.adrift      — Adrift
notifications.distress.undesignated — Undesignated distress
notifications.distress.abandon     — Abandon ship
notifications.distress.piracy      — Piracy/Armed attack
notifications.distress.mob         — Man overboard
notifications.distress.epirb       — EPIRB emission

Urgency and safety use a descriptive sub-path:

notifications.urgency.{description}
notifications.safety.{description}

Notification value format

All DSC notifications must include the required fields per the existing spec:

{
  "value": {
    "message": "Distress: Fire/Explosion from MMSI 211457160 at 54.3000N, 10.5000E",
    "state": "emergency",
    "method": ["visual", "sound"]
  },
  "timestamp": "2024-01-15T14:30:00Z",
  "$source": "nmea0183.DSC"
}

Recommended state values per DSC category:

• Distress (12): "emergency"
• Urgency (10): "alarm"
• Safety (08): "warn"

Semantic separation

Path	Meaning
notifications.fire	Own vessel: fire detected by onboard sensor
notifications.distress.fire	Received DSC: another vessel reports fire

This separation allows:

• UI applications to subscribe to notifications.distress.* and display incoming DSC calls (e.g. position on chart)
• Alarm systems to use notifications.fire etc. exclusively for own-vessel conditions
• No collision between local and external alarm sources

Delta examples

DSC Distress — Fire/Explosion from another vessel:

{
  "context": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
  "updates": [{
    "source": {
      "label": "nmea0183",
      "type": "NMEA0183",
      "talker": "",
      "sentence": "DSC"
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.distress.fire",
      "value": {
        "message": "Distress: Fire/Explosion from MMSI 211457160 at 54.3000N, 10.5000E",
        "state": "emergency",
        "method": ["visual", "sound"]
      }
    }]
  }]
}

DSC Urgency call:

{
  "context": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
  "updates": [{
    "source": {
      "label": "nmea0183",
      "type": "NMEA0183",
      "talker": "",
      "sentence": "DSC"
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.urgency.medicalAssistance",
      "value": {
        "message": "Urgency: Medical assistance required, MMSI 211457160",
        "state": "alarm",
        "method": ["visual", "sound"]
      }
    }]
  }]
}

DSC Safety call:

{
  "context": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
  "updates": [{
    "source": {
      "label": "nmea0183",
      "type": "NMEA0183",
      "talker": "",
      "sentence": "DSC"
    },
    "timestamp": "2024-01-15T14:30:00Z",
    "values": [{
      "path": "notifications.safety.navigationWarning",
      "value": {
        "message": "Safety: Navigational warning, MMSI 002111240",
        "state": "warn",
        "method": ["visual"]
      }
    }]
  }]
}

Routine calls (category 00)

Routine DSC calls do not generate notifications. They represent normal radio call requests and only update vessel position data if available.

Schema changes

New dscBranch definition

The existing notificationBranch definition uses a negative-lookahead regex that excludes the well-known names (mob, fire, sinking, etc.) at all nesting levels. This means notifications.distress.fire would be rejected — fire is blocked by the regex even inside distress.

To solve this, a new dscBranch definition is introduced in notifications.json. It explicitly lists the nature-of-distress names as properties (allowing fire, mob, etc. as sub-paths) and also permits arbitrary additional sub-paths via patternProperties.

Files modified

1. schemas/groups/notifications.json:
   • Add distress, urgency, safety to the negative-lookahead regex in notificationBranch
   • Add new dscBranch definition with well-known nature-of-distress properties (fire, mob, sinking, etc.) plus undesignated and epirb
2. schemas/vessel.json — Add distress, urgency, safety as well-known properties referencing dscBranch, update the regex
3. schemas/sar.json — Same as vessel.json
4. schemas/aircraft.json — Add properties block with distress, urgency, safety referencing dscBranch, update the regex
5. schemas/aton.json — Same as aircraft.json
6. mdbook/src/notifications.md — Document the new paths and DSC semantics

Backward compatibility

• Non-breaking: The notificationBranch pattern already allows arbitrary nesting, so paths like notifications.distress.someCustomKey work today. This RFC formalizes these paths as well-known and adds schema support for the nature-of-distress sub-paths.
• Migration: Existing DSC implementations should transition from notifications.fire (for received DSC) to notifications.distress.fire. The top-level paths remain valid for own-vessel alarms.

Interaction with other proposals

#655 — data attribute for alarm objects

This RFC is complementary to #655. The data attribute proposal would allow structured fields (position, MMSI) in the notification value, while this RFC addresses the notification path structure. Both can be adopted independently:

• Without data attribute: MMSI and position go in the message string
• With data attribute: { "message": "Distress: Fire", "state": "emergency", "method": ["visual", "sound"], "data": { "mmsi": "211457160", "position": { "latitude": 54.3, "longitude": 10.5 } } }

#668 — Notification path structure (notifications.mob vs notifications.mob.<key>)

The spec documentation says notifications.mob.* (with wildcard), suggesting sub-keys. The dscBranch pattern used here (notifications.distress.fire) is consistent with this structure. For multiple concurrent distress calls of the same nature, an MMSI sub-key could be used: notifications.distress.fire.211457160 — similar to how @bergie uses notifications.mob.<MMSI> in signalk-mob-notifier.

#378 — Notification Acknowledgements

DSC distress notifications may need different acknowledgement semantics than own-vessel alarms (a received distress relay is informational, not a local condition to resolve). This should be considered when implementing #378.

Open questions

1. MMSI in path: Should the MMSI of the calling vessel be included as a sub-key (e.g. notifications.distress.fire.211457160) to allow multiple concurrent distress calls of the same nature? This mirrors the notifications.mob.<MMSI> pattern from signalk-mob-notifier (Add data attribute to Alarm object used in Notification messages #655 discussion). Without MMSI sub-keys, a second distress call of the same nature would overwrite the first — only the most recent fire distress would be visible. With MMSI sub-keys, all concurrent distress calls coexist in the tree and can be subscribed to individually.
2. Structured data: Should the notification value object be extended with optional DSC-specific fields (MMSI, position, nature-of-distress code) beyond the message string? Or should this wait for the data attribute proposal (Add data attribute to Alarm object used in Notification messages #655)? Currently, MMSI and position are embedded in the human-readable message string. A UI that wants to plot the distress position on a chart would need to parse that string. A structured data object would make this machine-readable, but increases the scope of this RFC. Alternatively, this could be deferred to Add data attribute to Alarm object used in Notification messages #655 which proposes the same mechanism for all notification types.

[TwoCanPlugIn]

Not sure if SignalK also handles AIS Addressed Safety Messages and AIS Broadcast Messages, if not, perhaps these should be considered as appropriate.

Note also (and this is perhaps more of a parser issue), A DSC Distress transmission has a Format Specifier with a value of 12 (Distress), however the Category is "null", as Distress is assumed. On the other hand a DSC Distress Relay, has a Format Specifier of 16 (All Ships) and the Category is 12 (Distress).

I'm not sure how this is all tied together, but if I was thinking in terms of a relational database,, using something like SQL I would consider queries similar to

 SELECT vessel.mmsi, vessel.position, notification.category FROM vessels, notifications WHERE  notification.category = distress

or for an AIS Addressed Safety Message,

SELECT notification.message from notifications WHERE notification.mmsi = vessels.self.mmsi

Anyway, up to the experts....

[herostrat]

You make a valid point here. That's really good feedback imho. (Sorry for the LLM text, I let it structure my thoughts on my answer in order to get a more readable answer. The meaning behind it is from myself).

---

On AIS Safety Messages: Absolutely valid. AIS Message Type 12 (Addressed Safety) and Type 14 (Broadcast Safety) carry the same kind of navigational warnings as DSC Safety calls (category 08). Any path structure defined for DSC safety should naturally accommodate AIS safety messages too — they should not need separate paths just because they arrived via a different radio protocol.

On DSC Distress vs. Distress Relay: Correct, and worth clarifying. A DSC Distress call (Format Specifier 12) is sent directly by the vessel in distress — the Category field is empty because Distress is implied by the Format Specifier. A DSC Distress Relay (Format Specifier 16/All Ships, Category 12) is retransmitted by a third vessel. This is a parsing concern, not a path concern: both cases describe the same vessel in distress and should produce the same Signal K path. The difference is captured in $source.

On the SQL analogy: This is where your comment changed my thinking most. See below.

---

Rethinking the data model: received alerts under vessel context

Your SQL queries implicitly describe a data model where received alerts are stored under the originating vessel, not under vessels.self.notifications. This is exactly how Signal K already handles AIS data:

• AIS position from vessel 211457160 → vessels.211457160.navigation.position
• AIS name from vessel 211457160 → vessels.211457160.name

Following the same logic, a DSC distress call from vessel 211457160 should go to:

vessels.211457160.notifications.distress.fire

rather than:

vessels.self.notifications.distress.fire   ← current RFC proposal

Why this is better

1. Natural multi-vessel queries

A UI that wants to show all vessels in distress simply subscribes to:

vessels.*.notifications.distress.*

This works regardless of whether the alert arrived via DSC, AIS, LoRa, or any future transport. The transport is captured in $source.sentence, not in the path.

2. Multiple concurrent distress calls of the same nature are automatically separate

If two vessels both report fire at the same time, they produce two distinct paths:

vessels.211457160.notifications.distress.fire
vessels.305123456.notifications.distress.fire

No MMSI sub-key needed on self. No overwriting problem.

3. Consistent with existing AIS conventions

Signal K already stores received-from-others data under each vessel's context. DSC and AIS Safety Messages should follow the same pattern.

4. AIS Safety Messages fit naturally

vessels.211457160.notifications.safety.broadcast    ← AIS Message Type 14
vessels.211457160.notifications.safety.addressed    ← AIS Message Type 12, sent to us

Same paths, same subscription model, regardless of whether the safety message came via DSC or AIS.

5. Your SQL queries map directly to Signal K subscriptions

SELECT vessel.mmsi, vessel.position, notification.category FROM vessels, notifications WHERE notification.category = distress

In Signal K:

subscribe: vessels.*.notifications.distress.*

The response includes the vessel context (MMSI) and the notification value.

SELECT notification.message FROM notifications WHERE notification.mmsi = vessels.self.mmsi

In Signal K: subscribe to vessels.self.notifications.* — which only contains notifications addressed to or raised for the own vessel.

Revised path examples

Scenario	Path	Source
Own vessel fire alarm (sensor)	vessels.self.notifications.fire	onboard sensor
DSC Distress: fire from MMSI 211457160	vessels.211457160.notifications.distress.fire	$source: nmea0183.DSC
DSC Distress Relay: fire, original vessel 211457160	vessels.211457160.notifications.distress.fire	$source: nmea0183.DSC (relay)
AIS Safety Broadcast from MMSI 002111240	vessels.002111240.notifications.safety.broadcast	$source: nmea0183.VDM
DSC Urgency from MMSI 305000001	vessels.305000001.notifications.urgency	$source: nmea0183.DSC

The own-vessel reserved names (notifications.mob, notifications.fire, etc.) remain unchanged and continue to represent own-vessel conditions exclusively.

---

Open questions

1. Alerts without a known MMSI

DSC allows an "undesignated" distress where the nature is unknown and in rare cases the sender MMSI may be absent or invalid. Where should these go? A fallback to vessels.self.notifications.distress.undesignated seems reasonable for the unattributed case.

2. Non-MMSI transports

LoRa-based distress signals (e.g. from MOB devices) or internet-sourced safety alerts may not carry an MMSI. Should Signal K define an alternative vessel identifier for these, or use a synthetic identifier (e.g. device ID, call sign)? This is analogous to how Signal K handles vessels identified by UUID rather than MMSI.

3. Does this require server changes?

Currently, Signal K servers create vessel entries in the tree when AIS data arrives. DSC and AIS Safety Messages would need the same behaviour: receiving a DSC call from MMSI 211457160 should create or update a vessels.211457160 entry. Is this already handled by existing server logic, or does it require explicit spec guidance?

4. How does the operator get alerted?

Storing the notification under the originating vessel's context raises a practical question: the current Signal K alarm manager only watches vessels.self.notifications.* and triggers visual/sound alarms from there. A notification written to vessels.211457160.notifications.distress.fire would not trigger any alarm by default.

There are a few ways to solve this:

• Approach A — Extend the alarm manager (my preference): The server's alarm manager subscribes to vessels.*.notifications.distress.* (and urgency/safety) in addition to self. Any notification with state: emergency or state: alarm anywhere in the fleet tree triggers the operator alert, regardless of which vessel context it lives under. This is transport-agnostic and scales naturally to AIS, LoRa, and future sources. No redundant writes needed.

• Approach B — Dual-write: The parser writes to both the vessel context (for data) and vessels.self.notifications.* (for the alarm trigger). Backwards-compatible, but redundant and loses the multi-vessel separation for the self tree.

• Approach C — Server-side mirror: The server automatically mirrors any critical notification from vessels.*.notifications.distress.* into vessels.self.notifications.distress.*. Clean separation of concerns, but adds complexity to server logic.

Approach A feels right to me because it makes the alarm manager severity-aware across all vessel contexts rather than tying it to a single path prefix. This would also be a spec-level statement: servers conforming to Signal K should raise operator alerts for any state: emergency notification in the vessel tree, not just those under self.

---

Impact on the current RFC

This reframing changes the proposed paths but not the schema mechanisms. The dscBranch definition (allowing fire, mob, etc. as sub-paths within distress) would apply to any vessel's notification tree, not just self. The notificationBranch extension in vessel.json already covers all vessel entries.

I believe this model — received external alerts under the originating vessel's context, own-vessel alarms under self — is the right architectural direction, and that it scales cleanly to AIS Safety Messages, LoRa, and future transports without requiring new top-level path conventions for each one.

Feedback on the open questions, especially question 4, would be very welcome before updating the PR.

[panaaj]

The proposal, as it currently stands, uses the vessel.{id} as a context so is there any reason for mmsi notifications paths to be treated differently to self other than backwards compatibility?

Just as an FYI currently nmea alarms use the notifications.nmea path and should also be considered in this RFC so it is all encompassing.

[herostrat]

You make a valid point here...I actually also didn't know about the nmea path.

I thought about it a bit more and have now updated my proposal. But now, in order to have a solid/unified structure, I have a big problem in it - backwards compatibility :-/
The flat structure doesn't really fit in the unified model anymore imho

[panaaj]

@herostrat Probably should have mentioned it earlier but the recently released Notifications API documentation is here https://demo.signalk.org/admin/#/documentation/Developing/REST_APIs/Notifications_API.html

Note: Even though it is only in initial release it implements an Notifications Manager to allow notifications received by the server to be processed prior to emission to clients.

raise, update and clear operations are targeted for the next release which is in development.

[herostrat]

Awesome I (also) wasn't aware of this! Sorry, it's really hard to see every cog of the spec and signalk as a whole as a newcomer.

So this basically solves a lot of the problems I had left.

Only thing left in my mind is cross-vessel-awareness.
The Notification Manager needs to trigger operator alerts for state: emergency and state: alarm notifications from all vessel contexts, not just vessels.self. Without this, a distress call is correctly stored under vessels.211457160.notifications.distress.fire but produces no alarm on the operator's screen.

[ArjenR]

I somehow miss an item in the spec which is mentioned sometimes but not all the times. Probably due to the LLM assisted wording.
vessels.*.notifications.distress.* should this be vessels.*.notifications.distress.*,<uniqeu_id> to cover multiple alarms of the same type and origin, but not the same "item". In my case referenced in #668 the use case is for using bluetooth beacon as MOB alerts. If detection of one or more fails an MOB alarm can be raised with their unique name (crew member name) with a last detection time and position per missing beacon.

In an emergency this can happen at the same time or sub sequentially. Let's hope it never happens etc.

But in case it does, you do want multiple reports, multiple alerts for awareness. Multiple unique mob way-points for navigation applications etc.

The unique_id of course not limited to MMSI because in my example it isn't one.

[TwoCanPlugIn]

Little nit pick.

1. Alerts without a known MMSI
   DSC allows an "undesignated" distress where the nature is unknown and in rare cases the sender MMSI may be absent or invalid.

An undesignated alert just means the nature of distress hasn't been selected. The sailor has "madly" pressed the "Red" DSC switch.

However unless the VHF DSC radio has had a MMSI number programmed, it should not transmit a DSC message, so I think that SignalK is unlikely to receive a DSC message without a MMSI number.

An invalid nuber would be one that has not been issued by a valid authority, but other than an invalid country prefix, SignalK has no way of knowing whether a MMSI number has been assigned by a valid authority or Joe sailor has just "invented" their own number.

It coud be possible to look up the ITU MARS database, but that is perhaps beyond the scope of this discussion.