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>Deferred</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;
  <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'>
    <TeacherAssistant xmlns='http://tech.example.edu/hats' displayname='Teacher&apos; Assistant' xml:lang='en-us'/>
  </hats>
</presence>
    ]]></example>
    <p>Note: The format is open for debate. Possibilities include:</p>
    <ol>
      <li>
        <p>XML element in the hats namespace with name as a URI:</p>
        <p>&lt;hat xmlns='urn:xmpp:hats:0' name='http://tech.example.edu/hats#TeacherAssistant' display='Teacher&amp;apos;s Assistant' xml:lang='en-us'/&gt;</p>
        <p>Pro: Clients that don't understand the 'http://tech.example.edu/hats#TeacherAssistant' semantics can at least display a human-readable name. Names can be registered with the XMPP Registrar. Also appropriate as a field name in Ad-Hoc Commands.</p>
        <p>Con: Not a very Jabberish way of structuring information.</p>
      </li>
      <li>
        <p>XML element in the hats namespace with name scoped using Clark Notation:</p>
        <p>&lt;hat xmlns='urn:xmpp:hats:0' name='{http://tech.example.edu/hats}TeacherAssistant' display='Teacher&amp;apos;s Assistant' xml:lang='en-us'/&gt;</p>
        <p>Pro: Clients that don't understand the 'http://tech.example.edu/hats#TeacherAssistant' semantics can at least display a human-readable name. Names can be registered with the XMPP Registrar. Also integrates well with Ad-Hoc Commands.</p>
        <p>Con: Not a very Jabberish way of structuring information.</p>
      </li>
      <li>
        <p>XML element qualified by custom namespace:</p>
        <p>&lt;TeacherAssistant xmlns='http://tech.example.edu/hats' displayname='Teacher&amp;apos;s Assistant' xml:lang='en-us'/&gt;</p>
        <p>Pro: A more Jabberish way to structure information.</p>
        <p>Con: Clients won't show anything if they don't understand the custom namespace.</p>
      </li>
    </ol>
    <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.</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 displayName='Host' name='http://schemas.example.com/hats#host' xml:lang='en-us'/>
    <hat displayName='Presenter' name='http://schemas.example.com/hats#presenter' xml:lang='en-us'/>
  </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>