Skip to content

Commit 9208423

Browse files
edhelasedhelas
committed
XEP-0317: Hats, Update and complete the protocol
As a client developper the current Hats XEP is far from be usable and feature complete. The goal of those changes is to: - Allow clients to develop a nice UI to manage and assign hats, for example like Discord is doing (see https://support.discord.com/hc/en-us/articles/214836687-Discord-Roles-and-Permissions) - Reconciliate existing implementations and their specificities, see https://docs.ejabberd.im/tutorials/muc-hats/ - Those changes were meant to be backward compatible with the current 0.2.0 version This PR make the following changes: - Specify a urn:xmpp:hats:commands:dcreate command to add a hat to the available list - Specify a urn:xmpp:hats:commands:ddestroy command to destroy a hat from the list - Clarify how the service should broadcast the hat changes when it is edited, assigned, removed or destroyed - Specify a way for an entity to get the complete list of hats using the chatroom presence - Add a hue optional parameter allowing entities to assign a color to the hat that can be displayed properly in any conditions on the client (as explained in XEP-0392: Consistent Color Generation) - Fix some typos
1 parent a84e713 commit 9208423

File tree

1 file changed

+188
-12
lines changed

1 file changed

+188
-12
lines changed

‎xep-0317.xml

Lines changed: 188 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@
2424
<shortname>NOT_YET_ASSIGNED</shortname>
2525
&stpeter;
2626
&mwild;
27+
<revision>
28+
<version>0.3.0</version>
29+
<date>2025-04-30</date>
30+
<initials>tj</initials>
31+
<remark><p>Add hat creation and detruction flows; add hue optional parameter; add chatroom presence hats broadcast; complete disco#info; clarify how the service should broadcast updated hats; typos;</p></remark>
32+
</revision>
2733
<revision>
2834
<version>0.2.0</version>
2935
<date>2023-06-28</date>
@@ -55,7 +61,34 @@
5561
</section1>
5662

5763
<section1 topic='Discovery' anchor='disco'>
58-
<p>A MUC service that supports hats MUST advertise a &xep0030; feature of "urn:xmpp:hats:0".</p>
64+
<p>A MUC service that supports hats MUST advertise a &xep0030; feature of "urn:xmpp:hats:0" and the actions available to the requesting JID.</p>
65+
66+
<example caption='User’s client discovers the hat features of a MUC service'><![CDATA[
67+
<iq type='get'
68+
id='p87Ne'
69+
from='[email protected]/garden'
70+
to='[email protected]'>
71+
<query xmlns='http://jabber.org/protocol/disco#info'/>
72+
</iq>]]></example>
73+
<example caption='Room advertises hats support'><![CDATA[
74+
<iq type='result'
75+
id='p87Ne'
76+
to='[email protected]/garden'
77+
from='[email protected]'>
78+
<query xmlns='http://jabber.org/protocol/disco#info'>
79+
<identity
80+
category='conference'
81+
type='text'
82+
name='Shakespearean Chat Service'/>
83+
<feature var='urn:xmpp:hats:0'/>
84+
<feature var='urn:xmpp:hats:commands:dcreate'/>
85+
<feature var='urn:xmpp:hats:commands:ddestroy'/>
86+
<feature var='urn:xmpp:hats:commands:don'/>
87+
<feature var='urn:xmpp:hats:commands:doff'/>
88+
...
89+
</query>
90+
</iq>]]></example>
91+
5992
</section1>
6093

6194
<section1 topic='Protocol' anchor='protocol'>
@@ -74,7 +107,7 @@
74107
</hats>
75108
</presence>
76109
]]></example>
77-
<p>Every hat is uniquely identified by its URI. Hats also carry a human-readable title for display purposes. Within XMPP, a hat is contained within a &lt;hat/> element in the 'urn:xmpp:hats:0' namespace. This element MUST possess a 'uri' attribute (containing the hat's URI), a 'title' attribute containing the name of the hat for display purposes, and MAY contain an 'xml:lang' attribute that identifies the language used in the 'title' attribute. The &lt;hat/> element MAY contain additional custom payloads defined by other XEPs, or payloads specific to an implementation or deployment.</p>
110+
<p>Every hat is uniquely identified by its URI. Hats also carry a human-readable title for display purposes. Within XMPP, a hat is contained within a &lt;hat/> element in the 'urn:xmpp:hats:0' namespace. This element MUST possess a 'uri' attribute (containing the hat's URI), a 'title' attribute containing the name of the hat for display purposes, MAY contain an 'xml:lang' attribute that identifies the language used in the 'title' attribute and MAY contain a Hue Angle color that define the hat color to apply. The &lt;hat/> element MAY contain additional custom payloads defined by other XEPs, or payloads specific to an implementation or deployment.</p>
78111
<p>Entities may have multiple hats. The &lt;hats/> element is defined as a container of zero or more &lt;hat/> elements.</p>
79112

80113
<p>As noted, a participant can wear many hats. The following example shows a participant who is a MUC room owner and both a "host" and a "presenter" in an online meeting system. This system also demonstrates how hats can be annotated with custom information (here, the example &lt;badge/> element).</p>
@@ -87,20 +120,162 @@
87120
<item affiliation='owner' role='moderator'/>
88121
</x>
89122
<hats xmlns='urn:xmpp:hats:0'>
90-
<hat title='Host' uri='http://schemas.example.com/hats#host' xml:lang='en-us'>
91-
<badge xmlns="urn:example:badges" fgcolor="#000000" bgcolor="#58C5BA"/>
123+
<hat title='Host' uri='http://schemas.example.com/hats#host' hue='327.255249' xml:lang='en-us'>
124+
<badge xmlns="urn:example:badges" level="3"/>
92125
</hat>
93-
<hat title='Presenter' uri='http://schemas.example.com/hats#presenter' xml:lang='en-us'>
94-
<badge xmlns="urn:example:badges" fgcolor="#000000" bgcolor="#EC0524"/>
126+
<hat title='Presenter' uri='http://schemas.example.com/hats#presenter' hue='171.430664' xml:lang='en-us'>
127+
<badge xmlns="urn:example:badges" level="5"/>
95128
</hat>
96129
</hats>
97130
</presence>
98131
]]></example>
99132
</section2>
100-
<section2 topic='Adding a Hat' anchor='add'>
101-
<p>Hats are added and removed using &xep0050;.</p>
102-
<p>The following flow shows how to add a hat.</p>
103-
<example caption='Admin Requests to Add a Hat'><![CDATA[
133+
<section2 topic='Discovering existing Hats'>
134+
<p>An entity might be interested to get all the existing hats available in a chatroom.</p>
135+
<p>A chatroom MAY then publish the complete list of existing hats in its own presence.</p>
136+
<example caption='The chatroom publish the list of available hats'><![CDATA[
137+
<presence
138+
from='[email protected]'
139+
id='gt54a256'
140+
to='[email protected]/foo'>
141+
...
142+
<hats xmlns='urn:xmpp:hats:0'>
143+
<hat title='Host' uri='http://schemas.example.com/hats#host' hue='327.255249' xml:lang='en-us'/>
144+
<hat title='Presenter' uri='http://schemas.example.com/hats#presenter' hue='171.430664' xml:lang='en-us'/>
145+
...
146+
</hats>
147+
</presence>
148+
]]></example>
149+
</section2>
150+
<section2 topic='Create and update a Hat' anchor='create'>
151+
<p>Hats are created and destroyed using &xep0050;.</p>
152+
<p>The following flow shows how to create a hat.</p>
153+
<p>Updating a hat follows the same flow but set an existing "hat_uri". If a hat is updated the service SHOULD rebroadcast the related JID presences with the refreshed hat list.</p>
154+
<example caption='Admin Requests to Create a Hat'><![CDATA[
155+
<iq from='[email protected]/office'
156+
id='gd53a2b6'
157+
to='[email protected]'
158+
type='set'
159+
xml:lang='en'>
160+
<command xmlns='http://jabber.org/protocol/commands'
161+
action='execute'
162+
node='urn:xmpp:hats:commands:dcreate'/>
163+
</iq>
164+
]]></example>
165+
166+
<example caption='Service Returns Form to Admin'><![CDATA[
167+
<iq from='[email protected]'
168+
id='gd53a2b6'
169+
to='[email protected]/office'
170+
type='result'
171+
xml:lang='en'>
172+
<command xmlns='http://jabber.org/protocol/commands'
173+
node='urn:xmpp:hats:commands:dcreate'
174+
sessionid='A971D19A-2226-4DAD-B261-9D0886B9A026'
175+
status='executing'>
176+
<x xmlns='jabber:x:data' type='form'>
177+
<title>Creating a Hat</title>
178+
<instructions>Fill out this form to create a hat.</instructions>
179+
<field type='hidden' var='FORM_TYPE'>
180+
<value>urn:xmpp:hats:commands</value>
181+
</field>
182+
<field var='hat_title'
183+
type='text-single'
184+
label='Hat title'>
185+
<required/>
186+
</field>
187+
<field var='hat_uri'
188+
type='text-single'
189+
label='Hat URI'>
190+
<required/>
191+
</field>
192+
<field var='hat_hue'
193+
type='text-single'
194+
label='Hat Hue'/>
195+
</x>
196+
</command>
197+
</iq>
198+
]]></example>
199+
<example caption='Admin Submits Form'><![CDATA[
200+
<iq from='[email protected]/office'
201+
id='9fets723'
202+
to='[email protected]'
203+
type='set'
204+
xml:lang='en'>
205+
<command xmlns='http://jabber.org/protocol/commands'
206+
node='urn:xmpp:hats:commands:dcreate'
207+
sessionid='A971D19A-2226-4DAD-B261-9D0886B9A026'>
208+
<x xmlns='jabber:x:data' type='submit'>
209+
<field type='hidden' var='FORM_TYPE'>
210+
<value>urn:xmpp:hats:commands</value>
211+
</field>
212+
<field var='hat_title'>
213+
<value>Assistant</value>
214+
</field>
215+
<field var='hat_uri'>
216+
<value>http://tech.example.edu/hats#TeacherAssistant</value>
217+
</field>
218+
<field var='hat_hue'>
219+
<value>327.255249</value>
220+
</field>
221+
</x>
222+
</command>
223+
</iq>
224+
]]></example>
225+
<example caption='Service Informs Admin of Completion'><![CDATA[
226+
<iq from='[email protected]'
227+
id='9fets723'
228+
to='[email protected]/office'
229+
type='result'
230+
xml:lang='en'>
231+
<command xmlns='http://jabber.org/protocol/commands'
232+
node='urn:xmpp:hats:commands:don'
233+
sessionid='A971D19A-2226-4DAD-B261-9D0886B9A026'
234+
status='completed'/>
235+
</iq>
236+
]]></example>
237+
</section2>
238+
<section2 topic='Destroy a Hat' anchor='destroy'>
239+
<p>The following flow shows how to remove a hat.</p>
240+
<p>When a hat is destroyed, it is automatically removed from all the JIDs where it was assigned.</p>
241+
<p>The service SHOULD rebroadcast the related JID presences with the refreshed hats list.</p>
242+
<example caption='Admin Requests to Destroy a Hat'><![CDATA[
243+
<iq from='[email protected]/office'
244+
id='rei4n2b0'
245+
to='[email protected]'
246+
type='set'
247+
xml:lang='en'>
248+
<command xmlns='http://jabber.org/protocol/commands'
249+
action='execute'
250+
node='urn:xmpp:hats:commands:ddestroy'>
251+
<x xmlns='jabber:x:data' type='submit'>
252+
<field type='hidden' var='FORM_TYPE'>
253+
<value>urn:xmpp:hats:commands</value>
254+
</field>
255+
<field var='hat'>
256+
<value>http://tech.example.edu/hats#TeacherAssistant</value>
257+
</field>
258+
</x>
259+
</command>
260+
</iq>
261+
]]></example>
262+
<example caption='Service Informs Admin of Completion'><![CDATA[
263+
<iq from='[email protected]'
264+
id='rei4n2b0'
265+
to='[email protected]/office'
266+
type='result'
267+
xml:lang='en'>
268+
<command xmlns='http://jabber.org/protocol/commands'
269+
node='urn:xmpp:hats:commands:ddestroy'
270+
sessionid='A971D19A-2226-4DAD-B261-7D0886B9A123'
271+
status='completed'/>
272+
</iq>
273+
]]></example>
274+
</section2>
275+
<section2 topic='Assiging a Hat' anchor='add'>
276+
<p>Hats are assigned and removed using &xep0050;.</p>
277+
<p>The following flow shows how to assign a hat.</p>
278+
<example caption='Admin Requests to Assign a Hat'><![CDATA[
104279
<iq from='[email protected]/office'
105280
id='fdi3n2b6'
106281
to='[email protected]'
@@ -183,6 +358,7 @@
183358
</section2>
184359
<section2 topic='Removing a Hat' anchor='remove'>
185360
<p>The following flow shows how to remove a hat.</p>
361+
<p>When the hat is removed service SHOULD rebroadcast the related JID presence with the refreshed hat list.</p>
186362
<example caption='Admin Requests to Remove a Hat'><![CDATA[
187363
<iq from='[email protected]/office'
188364
id='fdi3n2b6'
@@ -200,15 +376,15 @@
200376
<value>[email protected]</value>
201377
</field>
202378
<field var='hat'>
203-
<option label='Teacher&apos;s Assistant'><value>http://tech.example.edu/hats#TeacherAssistant</value></option>
379+
<value>http://tech.example.edu/hats#TeacherAssistant</value>
204380
</field>
205381
</x>
206382
</command>
207383
</iq>
208384
]]></example>
209385
<example caption='Service Informs Admin of Completion'><![CDATA[
210386
<iq from='[email protected]'
211-
id='9fens61z'
387+
id='fdi3n2b6'
212388
to='[email protected]/office'
213389
type='result'
214390
xml:lang='en'>

0 commit comments

Comments
 (0)