xeps/xep-0090.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
  <!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
  <title>Entity Time</title>
  <abstract>This JEP provides canonical documentation of the existing 'jabber:iq:time' namespace currently used within the Jabber community.</abstract>
  &LEGALNOTICE;
  <number>0090</number>
  <status>Active</status>
  <type>Historical</type>
  <jig>Standards JIG</jig>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>iq-time</shortname>
  <schemaloc>
    <url>http://jabber.org/protocol/iq-time/iq-time.xsd</url>
  </schemaloc>
  &stpeter;
  <revision>
    <version>1.0</version>
    <date>2003-10-08</date>
    <initials>psa</initials>
    <remark>Per a vote of the Jabber Council, changed status to Active.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-05-22</date>
    <initials>psa</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction'>
  <p>The Jabber protocols have long included a method for discovering the time at another entity's location. This method makes use of the 'jabber:iq:time' namespace and has been documented variously in Internet-Drafts and elsewhere. Because this protocol is not required by &rfc2779;, the 'jabber:iq:time' namespace was removed from &xmppim;. This JEP fills the void for canonical documentation.</p>
</section1>
<section1 topic='Definition'>
  <p>The 'jabber:iq:time' namespace provides a standard way for Jabber entities to exchange information about the local time (e.g., to "ping" another entity or check network latency). The information is communicated in a request/response pair using an &IQ; element that contains a &QUERY; scoped by the 'jabber:iq:time' namespace. The following children of the &QUERY; element are allowed in an IQ result:</p>
  <ul>
    <li>&lt;utc/&gt; -- The time (in UTC) according to the responding entity. The format SHOULD be "CCYYMMDDThh:mm:ss" (see below). This element is REQUIRED in an IQ result.</li>
    <li>&lt;tz/&gt; -- The time zone in which the responding entity is located. This can be either a three-letter acronym or the full natural-language name of the timezone. <note>A list of time zone names and abbreviations is located at &lt;<link url='http://www.timeanddate.com/library/abbreviations/timezones/'>http://www.timeanddate.com/library/abbreviations/timezones/</link>&gt;.</note> This element is OPTIONAL in an IQ result.</li>
    <li>&lt;display/&gt; -- The time in a human-readable format. This element is OPTIONAL in an IQ result.</li>
  </ul>
</section1>
<section1 topic='Examples'>
    <example caption='Querying Another Entity for the Time'><![CDATA[
<iq type='get'
    from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='time_1'>
  <query xmlns='jabber:iq:time'/>
</iq>
    ]]></example>
    <example caption='A Response to the Query'><![CDATA[
<iq type='result'
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/orchard'
    id='time_1'>
  <query xmlns='jabber:iq:time'>
    <utc>20020910T17:58:35</utc>
    <tz>MDT</tz>
    <display>Tue Sep 10 12:58:35 2002</display>
  </query>
</iq>
    ]]></example>
    <p>The standard error conditions described in &jep0086; apply (e.g., service unavailable if the entity does not support the namespace).</p>
</section1>
<section1 topic='A Note on Time Formats'>
  <p>&jep0082; defines the lexical representation of dates, times, and datetimes in Jabber protocols. Unfortunately, the 'jabber:iq:time' namespace predates that definition, and uses a datetime format ("CCYYMMDDThh:mm:ss") that is inconsistent with JEP-0082 and &w3xmlschema2;. Because a large base of deployed software uses the old format, this JEP specifies that applications using 'jabber:iq:time' SHOULD use the old format, not the format defined in JEP-0082. In addition, note well that the datetime provided in the &lt;utc/&gt; element is explicitly UTC and therefore SHOULD NOT include the ending 'Z' character required by &iso8601;.</p>
</section1>
<section1 topic='Security Considerations'>
  <p>There are no security features or concerns related to this proposal.</p>
</section1>
<section1 topic='IANA Considerations'>
  <p>This JEP requires no interaction with &IANA;.</p>
</section1>
<section1 topic='Jabber Registrar Considerations'>
  <p>The 'jabber:iq:time' namespace is registered in the protocol namespaces registry maintained by the &REGISTRAR;.</p>
</section1>
<section1 topic='XML Schema'>
  <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:iq:time'
    xmlns='jabber:iq:time'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      JEP-0090: http://www.jabber.org/jeps/jep-0090.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence minOccurs='0'>
        <xs:element name='utc' type='xs:string' minOccurs='1'/>
        <xs:element name='tz' type='xs:string' minOccurs='0'/>
        <xs:element name='display' type='xs:string' minOccurs='0'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
  ]]></code>
</section1>
</jep>