xeps/xep-0306.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>Extensible Status Conditions for Multi-User Chat</title>
  <abstract>This document defines an extensible format for status conditions in Multi-User Chat, similar to the error format used in the core of XMPP.</abstract>
  &LEGALNOTICE;
  <number>0306</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <dependencies>
    <spec>RFC 6120</spec>
    <spec>XEP-0045</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>N/A</shortname>
  &stpeter;
  <revision>
    <version>0.2</version>
    <date>2011-12-14</date>
    <initials>psa</initials>
    <remark><p>Modified format to make it more backward compatible; incremented protocol namespace.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2011-08-26</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2011-08-12</date>
    <initials>psa</initials>
    <remark><p>Rough draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>Traditionally, &xep0045; has used numerical status codes similar to those used in HTTP and SMTP. Numerical codes were deprecated in the core of XMPP by &rfc3920; and are no longer even defined in the core schemas provided in &rfc6120; (see also &xep0086;). In an effort to modernize the Multi-User Chat (MUC) protocol, this document defines an extensible format for status conditions in MUC.</p>
</section1>

<section1 topic='Format' anchor='format'>
  <p>XML elements describing status conditions defined by this specification SHALL be qualified by the 'urn:xmpp:muc:conditions:1' namespace.</p>
  <p>The structure is as follows:</p>
  <code><![CDATA[
<status xmlns='http://jabber.org/protocol/muc#user'>
  <DEFINED-CONDITION>
    [<text xml:lang='langcode'>OPTIONAL descriptive text</text>]
    [OPTIONAL application-specific condition element]
  </DEFINED-CONDITION>
  [<DEFINED-CONDITION/>]
  [OPTIONAL application-specific condition element or elements]
</status>
  ]]></code>
  <p>That is, any &lt;status/&gt; element qualified by the existing http://jabber.org/protocol/muc#user' namespace (from XEP-0045) MAY contain one or more condition elements defined in this document (each of which MAY contain a human-readable &lt;text/&gt; element and MAY contain an application-specific condition element) and MAY contain one or more application-specific condition elements.</p>
  <p>An example follows.</p>
  <example caption="Service Sends New Occupant's Presence to New Occupant"><![CDATA[
<presence
    from='coven@chat.shakespeare.lit/thirdwitch'
    id='n13mt3l'
    to='hag66@shakespeare.lit/pda'>
  <x xmlns='http://jabber.org/protocol/muc#user'>
    <item affiliation='member' role='participant'/>
    <status code='100'/>
      <realjid-public xmlns='urn:xmpp:muc:conditions:1'/>
    </status>
    <status code='110'/>
      <self-presence xmlns='urn:xmpp:muc:conditions:1'/>
    </status>
  </x>
</presence>
  ]]></example>
</section1>

<section1 topic='Mapping of Existing Codes' anchor='mapping'>
  <p>The following table maps the existing numerical status codes (registered with the &REGISTRAR; at &MUCSTATUS;) to XML elements.</p>
  <table caption='Error Codes for http://jabber.org/protocol/muc#user Namespace'>
    <tr>
      <th>Code</th>
      <th>Element</th>
    </tr>
    <tr>
      <td>100</td>
      <td>&lt;realjid-public/&gt;</td>
    </tr>
    <tr>
      <td>101</td>
      <td>&lt;affiliation-changed/&gt;</td>
    </tr>
    <tr>
      <td>102</td>
      <td>&lt;unavailable-shown/&gt;</td>
    </tr>
    <tr>
      <td>103</td>
      <td>&lt;unavailable-not-shown/&gt;</td>
    </tr>
    <tr>
      <td>104</td>
      <td>&lt;configuration-changed/&gt;</td>
    </tr>
    <tr>
      <td>110</td>
      <td>&lt;self-presence/&gt;</td>
    </tr>
    <tr>
      <td>170</td>
      <td>&lt;logging-enabled/&gt;</td>
    </tr>
    <tr>
      <td>171</td>
      <td>&lt;logging-disabled/&gt;</td>
    </tr>
    <tr>
      <td>172</td>
      <td>&lt;non-anonymous/&gt;</td>
    </tr>
    <tr>
      <td>173</td>
      <td>&lt;semi-anonymous/&gt;</td>
    </tr>
    <tr>
      <td>174</td>
      <td>&lt;fully-anonymous/&gt;</td>
    </tr>
    <tr>
      <td>201</td>
      <td>&lt;room-created/&gt;</td>
    </tr>
    <tr>
      <td>210</td>
      <td>&lt;nick-assigned/&gt;</td>
    </tr>
    <tr>
      <td>301</td>
      <td>&lt;banned/&gt;</td>
    </tr>
    <tr>
      <td>303</td>
      <td>&lt;new-nick/&gt;</td>
    </tr>
    <tr>
      <td>307</td>
      <td>&lt;kicked/&gt;</td>
    </tr>
    <tr>
      <td>321</td>
      <td>&lt;removed-affiliation/&gt;</td>
    </tr>
    <tr>
      <td>322</td>
      <td>&lt;removed-membership/&gt;</td>
    </tr>
    <tr>
      <td>332</td>
      <td>&lt;removed-shutdown/&gt;</td>
    </tr>
  </table>
</section1>

<section1 topic='Security Considerations' anchor='security'>
  <p>The security considerations of <cite>XEP-0045</cite> apply.</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-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:muc:conditions:1</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
  <section2 topic='MUC Status Codes Registry' anchor='registrar-mucstatus'>
    <p>The XMPP Registrar is requested to add the elements defined in this specification to the existing registry for MUC status codes at &MUCSTATUS;.</p>
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:muc:conditions:1'
    xmlns='urn:xmpp:muc:conditions:1'
    elementFormDefault='qualified'>

  <xs:element name='affiliation-changed' type='MucStatusType'/>
  <xs:element name='banned' type='MucStatusType'/>
  <xs:element name='configuration-changed' type='MucStatusType'/>
  <xs:element name='fully-anonymous' type='MucStatusType'/>
  <xs:element name='kicked' type='MucStatusType'/>
  <xs:element name='logging-disabled' type='MucStatusType'/>
  <xs:element name='logging-enabled' type='MucStatusType'/>
  <xs:element name='new-nick' type='MucStatusType'/>
  <xs:element name='nick-assigned' type='MucStatusType'/>
  <xs:element name='non-anonymous' type='MucStatusType'/>
  <xs:element name='realjid-public' type='MucStatusType'/>
  <xs:element name='removed-affiliation' type='MucStatusType'/>
  <xs:element name='removed-membership' type='MucStatusType'/>
  <xs:element name='removed-shutdown' type='MucStatusType'/>
  <xs:element name='room-created' type='MucStatusType'/>
  <xs:element name='self-presence' type='MucStatusType'/>
  <xs:element name='semi-anonymous' type='MucStatusType'/>
  <xs:element name='unavailable-not-shown' type='MucStatusType'/>
  <xs:element name='unavailable-shown' type='MucStatusType'/>

  <xs:complexType name='MucStatusType'>
    <xs:sequence>
      <xs:element ref='text'/>
      <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded' processContents='lax'/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

  <xs:element name='text'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute ref='xml:lang' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

  ]]></code>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Dave Cridland and Ralph Meijer for their feedback.</p>
</section1>

</xep>