xeps/xep-0317.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Hats</title>
  <abstract>This specification defines a more extensible model for roles and affiliations in Multi-User Chat rooms.</abstract>
  &LEGALNOTICE;
  <number>0317</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0045</spec>
    <spec>XEP-0050</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  &stpeter;
  &mwild;
  <revision>
    <version>0.2.0</version>
    <date>2023-06-28</date>
    <initials>mw</initials>
    <remark><p>Select a syntax for hats.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2013-01-03</date>
    <initials>psa</initials>
    <remark><p>Initial published version approved for publication by the XMPP Council; clarified ad-hoc commands logic and syntax.</p></remark>
  </revision>
  <revision>
    <version>0.0.2</version>
    <date>2012-12-09</date>
    <initials>psa</initials>
    <remark><p>Described use of ad-hoc commands for adding and removing hats.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2012-12-06</date>
    <initials>psa</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>&xep0045; defines a widely-implemented XMPP extension for chatrooms, including basic roles and affiliations such as owner, administrator, and moderator. However, in many scenarios it is desirable to define different roles that are appropriate for the relevant application. Examples might include a "presenter" or a "scribe" in an online meeting system, a "representative" or a "manager" in a customer service application, a "comms officer" in a military chat system, an "incident manager" in a first responder system, a "teacher" or a "teacher's assistant" in an online classroom, specialized roles in online games, etc. To prevent confusion with standard MUC roles, these extended roles are call "hats", since a participant can "wear many hats" in a room.</p>
</section1>

<section1 topic='Discovery' anchor='disco'>
  <p>A MUC service that supports hats MUST advertise a &xep0030; feature of "urn:xmpp:hats:0".</p>
</section1>

<section1 topic='Protocol' anchor='protocol'>
  <section2 topic='Including a Hat in Presence' anchor='presence'>
    <p>MUC already includes a way for the room to signal the roles and affiliations of room occupants. Hats are signalled in a similar way. For example, the following presence notification would be sent by the room for an occupant who is a MUC room moderator but who also has a hat of "teacher's assistant" in an online classroom.</p>
    <example caption='Presence With Hat'><![CDATA[
<presence
    from='physicsforpoets@courses.example.edu/Terry'
    id='DE5C66DE-EC7D-4ECB-844A-B717A67CCE3D'
    to='steve@example.edu/tablet'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
  <hats xmlns='urn:xmpp:hats:0'>
    <hat uri='http://tech.example.edu/hats#TeacherAssistant' title='Teacher&apos;s Assistant' xml:lang='en-us'/>
  </hats>
</presence>
]]></example>
    <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>
    <p>Entities may have multiple hats. The &lt;hats/> element is defined as a container of zero or more &lt;hat/> elements.</p>

    <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>
    <example caption='Presence With Multiple Hats'><![CDATA[
<presence
    from='meeting123@meetings.example.com/Harry'
    id='D568A74F-E062-407C-83E9-531E91526516'
    to='someone@example.com/foo'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='owner' role='moderator'/>
  </x>
  <hats xmlns='urn:xmpp:hats:0'>
    <hat title='Host' uri='http://schemas.example.com/hats#host' xml:lang='en-us'>
        <badge xmlns="urn:example:badges" fgcolor="#000000" bgcolor="#58C5BA"/>
    </hat>
    <hat title='Presenter' uri='http://schemas.example.com/hats#presenter' xml:lang='en-us'>
        <badge xmlns="urn:example:badges" fgcolor="#000000" bgcolor="#EC0524"/>
    </hat>
  </hats>
</presence>
]]></example>
  </section2>
  <section2 topic='Adding a Hat' anchor='add'>
    <p>Hats are added and removed using &xep0050;.</p>
    <p>The following flow shows how to add a hat.</p>
    <example caption='Admin Requests to Add a Hat'><![CDATA[
<iq from='professor@example.edu/office'
    id='fdi3n2b6'
    to='physicsforpoets@courses.example.edu'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           action='execute'
           node='urn:xmpp:hats:commands:don'/>
</iq>
]]></example>
    <p>Unless an error occurs, the service returns the appropriate form.</p>
    <example caption='Service Returns Form to Admin'><![CDATA[
<iq from='physicsforpoets@courses.example.edu'
    id='fdi3n2b6'
    to='professor@example.edu/office'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='urn:xmpp:hats:commands:don'
           sessionid='A971D19A-2226-4DAD-B261-8D0886B9A026'
           status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Assigning a Hat</title>
      <instructions>Fill out this form to assign a hat.</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>urn:xmpp:hats:commands</value>
      </field>
      <field label='User Address'
             type='jid-single'
             var='accountjid'>
        <required/>
      </field>
      <field label='The role'
             type='list-single'
             var='hat'>
        <option label='Teacher'><value>http://tech.example.edu/hats#Teacher</value></option>
        <option label='Teacher&apos;s Assistant'><value>http://tech.example.edu/hats#TeacherAssistant</value></option>
        <option label='Test Proctor'><value>http://tech.example.edu/hats#Proctor</value></option>
      </field>
    </x>
  </command>
</iq>
]]></example>
    <example caption='Admin Submits Form'><![CDATA[
<iq from='professor@example.edu/office'
    id='9fens61z'
    to='physicsforpoets@courses.example.edu'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='urn:xmpp:hats:commands:don'
           sessionid='A971D19A-2226-4DAD-B261-8D0886B9A026'>
    <x xmlns='jabber:x:data' type='submit'>
      <field type='hidden' var='FORM_TYPE'>
        <value>urn:xmpp:hats:commands</value>
      </field>
      <field var='accountjid'>
        <value>terry.anderson@example.edu</value>
      </field>
      <field var='hat'>
        <value>http://tech.example.edu/hats#TeacherAssistant</value>
      </field>
    </x>
  </command>
</iq>
]]></example>
    <example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='physicsforpoets@courses.example.edu'
    id='9fens61z'
    to='professor@example.edu/office'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='urn:xmpp:hats:commands:don'
           sessionid='A971D19A-2226-4DAD-B261-8D0886B9A026'
           status='completed'/>
</iq>
]]></example>
    <p>Note: only one hat is added at a time, and the form uses a field of type "list-single" to enforce that logic.</p>
  </section2>
  <section2 topic='Removing a Hat' anchor='remove'>
    <p>The following flow shows how to remove a hat.</p>
    <example caption='Admin Requests to Remove a Hat'><![CDATA[
<iq from='professor@example.edu/office'
    id='fdi3n2b6'
    to='physicsforpoets@courses.example.edu'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           action='execute'
           node='urn:xmpp:hats:commands:doff'>
    <x xmlns='jabber:x:data' type='submit'>
      <field type='hidden' var='FORM_TYPE'>
        <value>urn:xmpp:hats:commands</value>
      </field>
      <field var='accountjid'>
        <value>terry.anderson@example.edu</value>
      </field>
      <field var='hat'>
        <option label='Teacher&apos;s Assistant'><value>http://tech.example.edu/hats#TeacherAssistant</value></option>
      </field>
    </x>
  </command>
</iq>
]]></example>
    <example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='physicsforpoets@courses.example.edu'
    id='9fens61z'
    to='professor@example.edu/office'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands'
           node='urn:xmpp:hats:commands:doff'
           sessionid='A971D19A-2226-4DAD-B261-8D0886B9A026'
           status='completed'/>
</iq>
]]></example>
  </section2>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>To follow.</p>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>

  <section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
    <p>The XMPP Registrar shall add "urn:xmpp:hats:0" to its registry of protocol namespaces.</p>
  </section2>

</section1>

<section1 topic='XML Schema' anchor='schema'>
  <p>To follow.</p>
</section1>

<section1 topic='Acknowledgements' anchor='acks'>
  <p>The concepts underlying this specification were first discussed several years ago at an XMPP Summit in Brussels, Belgium. Special thanks to Joe Hildebrand and Ralph Meijer for their contributions to those discussions. Thanks also to Matt Miller, Kevin Smith, and Matthew Wild for their feedback on the written specification.</p>
</section1>

</xep>