Update notification settings XEP after community feedback

xep-notification-filter.xml

@@ -26,6 +26,10 @@
   <shortname>notification-settings</shortname>
   &nicoco;
   <revision>
+    <version>0.0.2</version>
+    <date>2024-02-08</date>
+    <initials>nc</initials>
+    <remark><p>Update after discussions on the standards@ mailing list.</p></remark>
     <version>0.0.1</version>
     <date>2024-02-06</date>
     <initials>nc</initials>
@@ -36,16 +40,50 @@
   <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>
 </section1>
-<section1 topic='The notify element' anchor='element'>
-  <p>Notification settings are represented by the &lt;notify&gt; element. It only has one attribute named "when", which can take three values: "never", "always" and "on-mention". This element MUST be a child of an element identifying a specific chat by its JID, such as a &xep0402; &lt;extensions&gt;.</p>
-<example caption='An example of the notify-on element'><![CDATA[
-<notify xmlns=']]>&namespace;<![CDATA['
-        when='on-mention' />
+<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>
+<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[
+<notify xmlns=']]>&namespace;<![CDATA['>
+  <never client-type="pc" />
+  <on-mention client-type="mobile" />
+</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[
+<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>
+      ...
+    </custom-extension">
+    <custom-extension-2 xmlns="custom:ns-2">
+      <weather>raining</weather>
+      ...
+    </custom-extension-2">
+  </advanced>
+</notify>
+]]></example>
+  </section2>
 </section1>
 <section1 topic='Business Rules' anchor='rules'>
-  <p>The "on-mention" notification settings SHOULD NOT be used for direct chats but only for group chats.</p>
-  <p>The "on-mention" notification SHOULD rely on the user's nickname being spelled out in an incoming message in a group-chat, but MAY rely on other mechanism to "ping" the user, such as a &xep0461; or &xep0444; element referring a user's previous message.</p>
+  <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>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'>

xep.ent

@@ -1158,6 +1158,14 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
     <jid>[email protected]</jid>
   </author>
 " >
+<!ENTITY nicoco "
+  <author>
+    <firstname>Nicolas</firstname>
+    <surname>Cedilnik</surname>
+    <email>[email protected]</email>
+    <jid>[email protected]</jid>
+  </author>
+" >
 <!ENTITY moparisthebest "
   <author>
     <firstname>Travis</firstname>
@@ -1166,14 +1174,6 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates</link></span> <note>
     <jid>[email protected]</jid>
     <uri>https://moparisthebest.com/</uri>
  </author>
-" >   
-<!ENTITY nicoco "
-  <author>
-    <firstname>Nicolas</firstname>
-    <surname>Cedilnik</surname>
-    <email>[email protected]</email>
-    <jid>[email protected]</jid>
-  </author>
 " >
 
 <!-- XMPP Extension Protocols -->