xep-0120.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>Infobits</title>
  <abstract>NOTE: This proposal was retracted by the author on 2004-02-19.</abstract>
  <!--
  <abstract>A generic protocol for capturing granular information about users, servers, services, rooms, commands, nodes, files, and other phenomena on the Jabber network.</abstract>
  -->
  &LEGALNOTICE;
  <number>0120</number>
  <status>Retracted</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies><spec>XMPP Core</spec></dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>infobits</shortname>
  &stpeter;
  &linuxwolf;
  <revision>
    <version>0.5</version>
    <date>2004-01-22</date>
    <initials>psa</initials>
    <remark>Clarified rationale for not using namespaces; added bundles; added dataype attribute for &lt;bit/&gt; elements; added Matt Miller as co-author.</remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2003-12-14</date>
    <initials>psa</initials>
    <remark>Removed privacy list classes (which are to be defined in a separate proposal); added keynaming considerations; added more examples.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2003-10-22</date>
    <initials>psa</initials>
    <remark>Major overhaul. Moved entity and relationship elements to XEP-0123, and focused this document only on the information format itself, which in all cases must be contained within another protocol.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-09-28</date>
    <initials>psa</initials>
    <remark>Minor editorial revisions.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-09-23</date>
    <initials>psa</initials>
    <remark>Initial version.</remark>
  </revision>
</header>
<section1 topic='Introduction'>
  <p>Many Jabber protocols need to define metadata about "things" on the Jabber network; such things are not limited to entities that are addressable as JIDs (e.g., users, servers, services, and chatrooms) nor even to things that are addressable as &xep0060; or &xep0030; nodes (e.g., &xep0050;), but may include anything that Jabber entities can communicate about, including files sent via Jabber file transfer protocols (e.g., &xep0066; and &xep0096;), information published via pubsub protocols (e.g., &xep0118;), and other Jabber phenomena. To date, Jabber protocols have used disparate, specialized formats for capturing such meta-information. This document provides a generic information format that can be included whenever a protocol needs to define metadata about something on the network.</p>
</section1>
<section1 topic='Background'>
  <p>The format defined herein uses a simple "key-value" structure. Although this may seem contrary to the XML basis of Jabber technologies, there are at least two good reasons for pursuing this approach:</p>
  <ol>
    <li><p>Using namespaced XML elements would force implementations to maintain a record of all namespaces and to differentiate those that define actionable protocols (e.g., 'http://jabber.org/protocol/si') from those that define informational metadata formats (e.g., 'http://purl.org/dc/elements/1.1'); the only way to do this would be to maintain an internal list of all possible namespaces that might be encountered by an application on the network.</p></li>
    <li><p>Not all metadata formats that the Jabber community may want to use exist in stable XML representations (e.g., this is true of the vCard format) or in representations for which namespaces exist. In addition, some metadata formats (e.g., &foaf;) exist only in &w3rdf;, whose syntax is represented in XML but whose semantics impose a more complex structure that requires a specialized (non-XML) parser. As long as a clear mapping can be defined between such metadata formats and Jabber infobits, consistent information representation and exchange can be preserved.</p></li>
  </ol>
</section1>
<section1 topic='Protocol'>
  <section2 topic='Protocol Basics'>
    <p>The "infobits" protocol defined herein provides a data format only. The container element is &lt;info/&gt;, which is qualified by the 'http://jabber.org/protocol/infobits' namespace. There is one allowable child of the &lt;info/&gt; element -- &lt;bundle/&gt; -- and one allowable child of the &lt;bundle/&gt; element -- &lt;bit/&gt;. In order to provide the relevant metadata, the &lt;info/&gt; element MAY contain an unbounded number of &lt;bundle/&gt; elements, each of which MAY contain an unbounded number of &lt;bit/&gt; elements.</p>
    <p>Each &lt;bundle/&gt; element MUST possess a 'type' attribute, whose value specifies the aspect of reality to which the enclosed bits apply (e.g., geographical location). A &lt;bundle/&gt; element MAY also possess a 'context' attribute, whose value provides further specifying information about the kind of entities described by this bundle (e.g., a home address as opposed to a work address).</p>
    <p>Each &lt;bit/&gt; element MUST possess a 'key' attribute, whose value specifies the name of the key (this MUST be an NMTOKEN as defined in &w3xml;). A &lt;bit/&gt; element MAY also possess a 'datatype' attribute, whose value specifies the datatype of the key (which SHOULD be a datatype specified in &w3xmlschema2; or in a registry of values maintained by the XMPP Registrar, such as those described in &xep0122;). The &lt;bit/&gt; element SHOULD contain XML character data that specifies the relevant value of the 'key'. A &lt;bundle/&gt; element MAY contain more than one &lt;bit/&gt; element with the same value for the 'key' attribute when necessary (e.g., two instances of 'weblog' if the person has multiple weblogs), but obviously SHOULD NOT do so if a collision would occur (e.g., two instances of 'lat' and 'lon' to define a geographical location).</p>
    <p><em><strong>Note well:</strong> no keys are defined in this document. All such keys MUST be defined in separate specifications. Keys and associated values shown in this document are provided for explanatory purposes only.</em></p>
  </section2>
  <section2 topic='Discovering Support'>
    <p>When an entity is queried via &xep0030; regarding the features it supports, it SHOULD include the 'http://jabber.org/protocol/infobits' namespace.</p>
  </section2>
</section1>
<section1 topic='Examples'>
  <section2 topic='Requesting Geographical Location Information From Another Entity'>
    <p>This set of examples is borrowed from &xep0080;.</p>
    <example caption='Requestor Requests Geolocation'><![CDATA[
<iq type='get'
    from='linuxwolf@outer-planes.net/gabber2'
    to='stpeter@jabber.org'
    id='geoloc1'>
  <info xmlns='http://jabber.org/protocol/infobits'>
    <bundle type='http://jabber.org/protocol/infobits/bundles/geoloc'/>
  </info>
</iq>
]]></example>
    <example caption='Entity Returns Geolocation Result'><![CDATA[
<iq type='result'
    from='stpeter@jabber.org'
    to='linuxwolf@outer-planes.net/gabber2'
    id='geoloc1'>
  <info xmlns='http://jabber.org/protocol/infobits'>
    <bundle type='http://jabber.org/protocol/infobits/bundles/geoloc'>
      <bit key='geo.lat'>39.75477</bit>
      <bit key='geo.lon'>-104.99768</bit>
      <bit key='geo.alt'>1609</bit>
      <bit key='geo.gpserror'>10</bit>
      <bit key='DC.created'>20040116T17:15:25</bit>
      <bit key='DC.description'>Jabber, Inc.</bit>
    </bundle>
  </info>
</iq>
]]></example>
  </section2>
  <section2 topic='Requesting All Infobits From Another Entity'>
    <example caption='Requestor Requests Information'><![CDATA[
<iq type='get'
    from='linuxwolf@outer-planes.net/gabber2'
    to='stpeter@jabber.org'
    id='all1'>
  <info xmlns='http://jabber.org/protocol/infobits'/>
</iq>
]]></example>
    <example caption='Entity Returns Information Result'><![CDATA[
<iq type='result'
    from='stpeter@jabber.org'
    to='linuxwolf@outer-planes.net/gabber2'
    id='all1'>
  <info xmlns='http://jabber.org/protocol/infobits'>
    <bundle type='http://jabber.org/protocol/infobits/bundles/geoloc'>
      <bit key='geo.lat'>39.75477</bit>
      <bit key='geo.lon'>-104.99768</bit>
      <bit key='geo.alt'>1609</bit>
      <bit key='geo.gpserror'>10</bit>
      <bit key='DC.created'>20040116T17:15:25</bit>
      <bit key='DC.description'>Jabber, Inc.</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/name'>
      <bit key='vcard.prefix'>Mr.</bit>
      <bit key='vcard.givenname'>Peter</bit>
      <bit key='vcard.familyname'>Saint-Andre</bit>
      <bit key='vcard.nick'>stpeter</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/address'
            context='work'>
      <bit key='addr.floor'>6</bit>
      <bit key='vcard.street'>1899 Wynkoop Street</bit>
      <bit key='vcard.city'>Denver</bit>
      <bit key='vcard.region'>Colorado</bit>
      <bit key='vcard.country'>USA</bit>
      <bit key='vcard.pcode'>80202</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/address'
            context='home'>
      <bit key='vcard.city'>Denver</bit>
      <bit key='vcard.region'>Colorado</bit>
      <bit key='vcard.country'>USA</bit>
      <bit key='vcard.pcode'>80209</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/tel'
            context='work'>
      <bit key='vcard.phone'>+1 303-308-3282</bit>
      <bit key='vcard.fax'>+1 303-308-3215</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/tel'
            context='home'>
      <bit key='vcard.phone'>+1 303-555-1212</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/activity'>
      <bit key='rpid.activity'>busy</bit>
      <bit key='jsf.action'>writing</bit>
      <bit key='DC.created'>20040116T16:56:37</bit>
    </bundle>
    <bundle type='http://jabber.org/protocol/infobits/bundles/mood'>
      <bit key='jsf.mood'>grumpy</bit>
      <bit key='DC.created'>20040116T16:56:37</bit>
    </bundle>
  </info>
</iq>
]]></example>
  </section2>
  <section2 topic='Publishing Tune Information'>
    <p>This set of examples is borrowed from &xep0118;.</p>
    <example caption='User Publishes Tune Information'><![CDATA[
<iq type='set'
    from='stpeter@jabber.org/work'
    to='pubsub.jabber.org'
    id='tunes123'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <info xmlns='http://jabber.org/protocol/infobits'>
          <bundle type='http://jabber.org/protocol/infobits/bundles/tunes'>
            <bit key='DC.creator'>Yes</bit>
            <bit key='DC.title'>Heart of the Sunrise</bit>
            <bit key='DC.source'>Yessongs</bit>
            <bit key='DC.identifier'>3</bit>
            <bit key='DC.extent'>P11M26S</bit>
          </bundle>
        </info>
      </item>
    </publish>
  </pubsub>
</iq>
]]></example>
    <example caption='Tune Information is Delivered to All Subscribers'><![CDATA[
<message
    from='pubsub.jabber.org'
    to='maineboy@jabber.org/laptop'>
  <x xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node='generic/tunes/stpeter@jabber.org'>
      <item id='current'>
        <info xmlns='http://jabber.org/protocol/infobits'>
          <bundle type='http://jabber.org/protocol/infobits/bundles/tunes'>
            <bit key='DC.creator'>Yes</bit>
            <bit key='DC.title'>Heart of the Sunrise</bit>
            <bit key='DC.source'>Yessongs</bit>
            <bit key='DC.identifier'>3</bit>
            <bit key='DC.extent'>P11M26S</bit>
          </bundle>
        </info>
      </item>
    </items>
  </x>
</message>
]]></example>
  </section2>
</section1>
<section1 topic='Security Considerations'>
  <p>Data provided via the infobits protocol MAY be world-readable. Access control considerations MUST be defined by any protocol that makes use of infobits.</p>
</section1>
<section1 topic='Internationalization Considerations'>
  <p>Info key names registered with the XMPP Registrar MUST be considered as identifiers, not English-language words. For purposes of internationalization, an identifier SHOULD be rendered as a word or phrase that is appropriate to the end user's preferred language.</p>
</section1>
<section1 topic='IANA Considerations'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations'>
  <section2 topic='Namespaces'>
    <p>Upon advancement of this proposal to a status of Draft, the &REGISTRAR; shall add the 'http://jabber.org/protocol/infobits' namespace to its registry of official namespaces.</p>
  </section2>
  <section2 topic='Registries'>
    <p>The XMPP Registrar shall maintain a registry of infobit keynames and associated information.</p>
    <p>All keynames MUST begin with a short prefix string (letters and numbers only), followed by the '.' character used as a separator, followed by the name of the key as determined by the particular specification or organization that is identified with the prefix. Arbitrary keynames SHOULD begin with a prefix consisting of the capital 'X' character.</p>
    <p>The XMPP Registrar shall at its discretion reserve certain keyname prefixes for use in specifying particular classes of information. One example is the prefix 'DC', which is reserved for use by infobits specified by the &DUBLINCORE; (for details, see &xep0121;). Furthermore, the XMPP Registrar shall reserve the "XMPP" prefix for infobits related to documents created by the &XMPPWG; or its successors, and shall reserve the upper-case versions of all protocol "shortnames" specified in XMPP Extension Protocol specifications (e.g., a prefix of "MUC" for infobits related to &xep0045;).</p>
    <p>In order to prevent naming collisions, infobits that will be used in public protocols that may interoperate with other protocols on the network SHOULD be registered with the XMPP Registrar, and MUST be so registered if they are defined in XMPP Extension Protocol specifications (however, registration of private keys is NOT REQUIRED). Registration with the XMPP Registrar shall be considered to entail reservation of that infobit on the network, and a registered bit MUST NOT be re-used by other protocols and applications for purposes other than those implied by the registry entry.</p>
    <p>In addition to the key name, the following data may be provided (but is not required) for each bit:</p>
    <ol>
      <li>datatype -- provide only if well-defined; otherwise assume string</li>
      <li>doc -- the public identifier (e.g., XEP number or RFC number) of the document in which the info name is defined</li>
      <li>valid values -- a series of &lt;value/&gt; elements, encapsulated within a &lt;values/&gt; parent whose 'type' attribute is set to "exhaustive" (these are the only valid values) or "nonexhaustive" (these are some of the valid values, but this list is not exhaustive and other values may be provided)</li>
    </ol>
    <p>The registry format is as follows:</p>
    <code><![CDATA[
<bit key='thename'>
  <datatype>some datatype</datatype>
  <doc>some document identifier</doc>
  <values type='[exhaustive|nonexhaustive]'>
    <value>first value</value>
    <value>second value</value>
  </values>
</bit>
]]></code>
  </section2>
</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='http://jabber.org/protocol/infobits'
    xmlns='http://jabber.org/protocol/infobits'
    elementFormDefault='qualified'>

  <xs:element name='info'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='bundle' minOccurs='1' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='bundle'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='bit' minOccurs='1' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='type' type='xs:string' use='required'/>
      <xs:attribute name='context' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='bit'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='key' type='xs:NMTOKEN' use='required'/>
          <xs:attribute name='datatype' type='xs:NMTOKEN' use='optional'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
]]></code>
</section1>
<section1 topic='Historical Note'>
  <p>Before defining a new protocol for metadata, the primary author of this proposal investigated several promising technologies that could be used to meet the above requirements -- in particular, the Friend of a Friend (FOAF) vocabulary, which is a subset of the Resource Description Framework (RDF). Ultimately, the primary author concluded that, while FOAF and RDF have many merits, they are not ideal for use on the Jabber network. In particular:</p>
  <ol>
    <li>Although RDF uses XML syntax, processing of RDF requires an RDF parser, not an XML parser. The benefits of using RDF were outweighed by the costs of requiring an RDF parser in every application that would use the metadata format.</li>
    <li>By design, FOAF and RDF allow an entity to define information about any other entity; this gives rise to significant concerns about data integrity, which have not been solved (and perhaps even cannot be solved) within the context of an RDF application.</li>
    <li>The processes for proposing, changing, and approving RDF-related namespaces are not well defined and are outside the control or influence of the Jabber community.</li>
  </ol>
  <p>Given these and other concerns, the primary author concluded that the best course would be to define an extensible XML protocol that can be processed using tools that are standard within existing Jabber/XMPP implementations, that allows only the entity itself to define metadata about itself, and that is under the control of the Jabber/XMPP community.</p>
</section1>
</xep>