Skip to content

XEP-0492: Rework whole spec and fix schema #1478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 13, 2025
Merged

XEP-0492: Rework whole spec and fix schema #1478

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 83 additions & 32 deletions xep-0492.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY namespace "urn:xmpp:notification-settings:0">
<!ENTITY namespace "urn:xmpp:notification-settings:1">
<!ENTITY xep-number "0492">
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
Expand All @@ -19,12 +19,26 @@
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>XEP-0163</spec>
<spec>XEP-0402</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>notification-settings</shortname>
&nicoco;
&tmolitor;
<revision>
<version>0.2.0</version>
<date>2025-10-25</date>
<initials>tm</initials>
<remark>
<ul>
<li>Rework the spec to use more of the Service Discovery Identities registry</li>
<li>Fix the XML schema</li>
<li>Move the &lt;advanced/&gt; element into the notification setting element</li>
<li>Bump the namespace</li>
</ul>
</remark>
</revision>
<revision>
<version>0.1.0</version>
<date>2024-07-01</date>
Expand All @@ -50,53 +64,77 @@
</header>
<section1 topic='Introduction' anchor='intro'>
<p>"Notifications" are (usually) pop-up windows that appear in a visible area of the screen even when the emitting application is in the background, often triggering a sound alert. <em>Instant</em> messaging clients expectedly use notifications to inform users when they receive a message.</p>
<p>Users may want to customise which conversations should trigger notifications and under which conditions. In practice, this is already implemented in many instant messaging clients, including XMPP clients. This specification proposes a mechanism to synchronise per-discussion notification settings across different XMPP clients.</p>
<p>Users may want to customise which conversations should trigger notifications and under which conditions. In practice, this is already implemented in many instant messaging clients, including XMPP clients. This specification proposes a mechanism to synchronise per-discussion notification settings across different XMPP clients and other XMPP based applications.</p>
</section1>
<section1 topic='Protocol' anchor='protocol'>
<section2 topic='The notify element' anchor='notify'>
<p>Notification settings are represented by the &lt;notify&gt; element. This element MUST be a child of an element identifying a specific chat by its JID, such as a &xep0402; &lt;extensions&gt;.</p>
<p>This protocol specifies three children for the &lt;notify&gt; element, each corresponding to a notification setting: &lt;always&gt; &lt;on-mention&gt; and &lt;never&gt;.</p>
<p>This protocol specifies three notification elements as children for the &lt;notify&gt; element, each corresponding to a notification setting: &lt;always&gt; &lt;on-mention&gt; and &lt;never&gt;. A notification element without attributes is called a "fallback element".</p>
<example caption='Most basic example'><![CDATA[
<notify xmlns=']]>&namespace;<![CDATA['>
<never />
</notify>
]]></example>
</section2>
<section2 topic='Client types' anchor='client-types'>
<p>One might want to choose different notification settings depending on the client type. In this case, a "client-type" attribute can be added to the notification setting, using registered Service Discovery Identities.</p>
<example caption='An example of notification settings by client type'><![CDATA[
<section2 topic='Identities' anchor='identities'>
<p>Applications MAY choose different notification settings depending on their own Service Discovery Identity. In this case, the two optional attributes '<tt>identity-category</tt>' and '<tt>identity-type</tt>' MAY be added to the notification element, using values registered in the Service Discovery Identities registry at &DISCOCATEGORIES;.</p>
<p>The '<tt>identity-type</tt>' attribute MAY be omitted, if the notification setting should apply to a whole Identity Category. You MUST NOT add the '<tt>identity-type</tt>' attribute without an accompanying '<tt>identity-category</tt>' attribute.</p>
<example caption='An example of notification settings by identity'><![CDATA[
<notify xmlns=']]>&namespace;<![CDATA['>
<never client-type="pc" />
<on-mention client-type="mobile" />
<never identity-category="client" identity-type="pc" />
<on-mention identity-category="client" identity-type="phone" />
<on-mention identity-category="gateway" />
<always />
</notify>
]]></example>
</section2>
<section2 topic='Advanced notification settings' anchor='advanced'>
<p>Finally, clients can use this specification to synchronise finer-grained notification settings using custom namespaces.</p>
<example caption='An example of notification settings by client type'><![CDATA[
<p>Finally, clients can use this specification to synchronise finer-grained notification settings using custom namespaces in the optional &lt;advanced/&gt; child of the notification elements.</p>
<p>The &lt;advanced/&gt; element SHOULD NOT be empty.</p>
<example caption='Complex example of finer-grained notification settings'><![CDATA[
<notify xmlns=']]>&namespace;<![CDATA['>
<never client-type="pc" />
<on-mention client-type="mobile" />
<advanced>
<custom-extension xmlns="custom:ns-1">
<when day-of-week="monday">night-time-only</day-of-week>
<never identity-category="client" identity-type="pc">
<advanced>
<my-custom-extension xmlns="custom:ns-1">
<when day-of-week="monday">night-time-only</day-of-week>
...
</custom>
<cool-custom-extension-2 xmlns="custom:ns-2">
<weather>raining</weather>
...
</custom>
...
</custom-extension">
<custom-extension-2 xmlns="custom:ns-2">
<weather>raining</weather>
</advanced>
</never>
<on-mention identity-category="client" identity-type="phone" />
<on-mention identity-category="gateway" />
<always>
<advanced>
<better-custom-extension xmlns="custom:ns-3">
<when day-of-week="saturday" />
<when day-of-week="sunday" />
...
</custom>
...
</custom-extension-2">
</advanced>
</advanced>
</always>
</notify>
]]></example>
</section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
<p>Entities implementing this specification MUST NOT delete or alter the advanced notification settings they do not support when updating the notification settings for a given chat.</p>
<p>If there is more than one notification setting for a given chat, entities implementing this specification MUST specify which client type they apply to. The (notification setting, client-type) pairs MUST be unique.</p>
<p>Entities using advanced notification settings SHOULD attempt to provide the basic notification setting which is the closest to what they offer as a fallback for other entities.</p>
<p>Applications implementing this specification MUST NOT delete or alter the &lt;advanced /&gt; notification settings they do not support when updating the notification settings for a given conversation.</p>
<p>When reading the notification settings for a given conversation, applications implementing this specification MUST use the element most specific to their own application identity. Sorted from high to low specifity, this is:</p>
<ol>
<li>Matching '<tt>identity-category</tt>' and '<tt>identity-type</tt>' attributes</li>
<li>Matching '<tt>identity-category</tt>' attribute</li>
<li>Fallback element without '<tt>identity-category</tt>' and '<tt>identity-type</tt>' attributes</li>
</ol>
<p>When writing the notification settings, applications MAY use the '<tt>identity-category</tt>' and '<tt>identity-type</tt>' attributes as described in the <link url="#identities">Identities</link> section. If a fallback element without any attributes isn't present, the application SHOULD add it with the same settings. As secondary fallback, it MAY also add a notification setting having only the '<tt>identity-category</tt>' attribute, if not already present.</p>
<p>There SHALL NOT be more than one notification element having the same name, attributes and attribute values.</p>
<p>Applications using the &lt;advanced/&gt; child SHOULD attempt to choose the parent notification element being the closest to what they offer as a fallback for other applications not supporting the advanced settings.</p>
<p>In the absence of any notification settings for a given conversation, "always" SHOULD be assumed for direct chats and private group chats, and <tt>on-mention</tt> for public group chats.</p>
<p>The "on-mention" notification MAY rely on the user's nickname being spelled out in an incoming message in a group chat, but SHOULD rely on mechanisms to explicitly "ping" the user, such as a &xep0461; element referring a user's previous message or a specific mention, such as a &xep0372; mention.</p>
<p>In the absence of a notification settings for a given chat, "always" SHOULD be assumed for direct chats and private group chats, and "on-mention" for public group chats.</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>See considerations in &xep0402;.</p>
Expand Down Expand Up @@ -135,15 +173,28 @@

<xs:element name='notify'>
<xs:complexType>
<xs:attribute name='when' default='always'>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='always'/>
<xs:enumeration value='never'/>
<xs:enumeration value='on-mention'/>
</xs:restriction>
</xs:attribute>
<xs:sequence>
<xs:element name='always' type='setting' minOccurs='0' maxOccurs='unbounded'/>
<xs:element name='on-mention' type='setting' minOccurs='0' maxOccurs='unbounded'/>
<xs:element name='never' type='setting' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>

<xs:complexType name="setting">
<xs:sequence>
<xs:element name='advanced' minOccurs='0' maxOccurs='1'>
<xs:complexType>
<xs:sequence>
<xs:any namespace='##other' minOccurs='1' maxOccurs='unbounded' processContents='lax'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name='identity-category' type='xs:string' use='optional'/>
<xs:attribute name='identity-type' type='xs:string' use='optional'/>
</xs:complexType>

</xs:schema>
]]></code>
</section1>
Expand Down
Loading