xeps/inbox/pubsub-uri.xml

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE xep SYSTEM "xep.dtd" [
  <!ENTITY SELF "XEP-xxxx">
  <!ENTITY % ents SYSTEM "xep.ent">
  %ents;
  <!ENTITY ABNF  "<span class='ref'><link url='http://tools.ietf.org/html/rfc5234'>ABNF</link></span> <note>RFC 5234: Augmented BNF for Syntax Specifications: ABNF &lt;<link url='http://tools.ietf.org/html/rfc5234'>http://tools.ietf.org/html/rfc5234</link>&gt;.</note>" >
  <!ENTITY UTF-8 "<span class='ref'><link url='http://tools.ietf.org/html/rfc3629'>UTF-8</link></span> <note>RFC 3629: UTF-8, a transformation format of ISO 10646 &lt;<link url='http://tools.ietf.org/html/rfc3629'>http://tools.ietf.org/html/rfc3629</link>&gt;.</note>" >
]>

<?xml-stylesheet type="text/xsl" href="xep.xsl"?>

<xep>

  <header>

    <title>The 'xmpp.pubsub' URI Scheme</title>

    <abstract>This document defines the format of Uniform Resource Identifiers
    (URIs) to identify nodes in the context of Publish-Subscribe services as
    well as items within the scope of such nodes.</abstract>

    &LEGALNOTICE;

    <number>xxxx</number>
    <status>ProtoXEP</status>
    <type>Standards Track</type>
    <sig>Standards</sig>
    <approver>Council</approver>

    <dependencies>
      <spec>XMPP Core</spec>
      <spec>XEP-0060</spec>
      <spec>RFC 3986</spec>
    </dependencies>

    <supersedes/>
    <supersededby/>

    <shortname>NOT_YET_ASSIGNED</shortname>

    <author>
      <firstname>Klaus</firstname>
      <surname>Hartke</surname>
      <email>hartke@tzi.org</email>
      <jid>nx@jabber.org</jid>
    </author>

    <revision>
      <version>0.0.1</version>
      <date>2012-01-14</date>
      <initials>kh</initials>
      <remark>
        <p>Initial draft.</p>
      </remark>
    </revision>

  </header>

  <section1 topic="Introduction" anchor="intro">
    <p>&xep0060; is an XMPP protocol extension for generic publish-subscribe
    functionality. Several protocols use Uniform Resource Identifiers (URIs) to
    refer to data. By defining a URI scheme for pubsub data, the gap between
    these two worlds is bridged. The 'xmpp.pubsub' URI scheme defined here can
    be used to reference any node within the context of a specific pubsub
    service, or an item within the scope of a specific node.</p>

    <p class="box">Note: <cite>XEP-0060</cite>, Section 4.6.1, specifies the
    use of JIDs for addressing pubsub nodes, which in combination with the
    &xmppiri; already provides a way to generate URIs for these nodes. This,
    however, does not allow addressing nodes that are addressable as a JID plus
    node (see <cite>XEP-0060</cite>, Section 4.6.2), and also does not allow
    referring to the items published to nodes.</p>
  </section1>

  <section1 topic="Requirements" anchor="reqs">
    <p>The URI scheme defined herein is designed to meet the following
    requirements:</p>

    <ol>
      <li>Provide a way to address pubsub items and nodes.</li>
      <li>Address pubsub nodes as JID plus NodeID.</li>
      <li>Enable applications to fabricate a URI given a JID and a NodeID.
      </li>
      <li>Support relative URI references.</li>
    </ol>
  </section1>

  <section1 topic="Syntax" anchor="syntax">
    <p>The URI scheme follows the generic syntax from &rfc3986; and is
    described using &ABNF;. The "host", "query", "gen-delims", "sub-delims",
    "pct-encoded", "reserved" and "unreserved" rules are defined in
    <cite>RFC 3986</cite>, and the "authxmpp" and "nodeid" rule are
    defined in <cite>RFC 5122</cite>.</p>

    <code>
<![CDATA[
xmpp-pubsub-URI = "xmpp.pubsub:" [ "//" authxmpp "/" ] pubsub-path [ "?" query ]
pubsub-path     = [ nodeid "@" ] host [ "/" [ pubsub-nodeid [ "/" [ pubsub-itemid ] ] ] ]
pubsub-nodeid   = 1*( unreserved / pct-encoded / sub-delims )
pubsub-itemid   = 1*( unreserved / pct-encoded / sub-delims )
]]>
    </code>

    <p>Unless specified in the URI, the authority ("authxmpp") is assumed to be
    locally known, and the NodeID ("pubsub-nodeid") to refer to the root node
    (i.e., the service itself).</p>

    <p>A number of characters that can appear in an NodeID and ItemID MUST be
    percent-encoded in pubsub-nodeid and pubsub-itemid respectively. These are
    the characters that cannot appear in a URI according to <cite>RFC
    3986</cite> as well as "%" (because it is used for percent-encoding) and
    all the characters in the "gen-delims" set (i.e., ":", "/", "?", "#", "[",
    "]" and "@").</p>

    <p>Note that this specification, like any URI scheme specification, does
    not define syntax or meaning of a fragment identifier (see <cite>RFC
    3986</cite>, Section 3.5), because these depend on the type of a retrieved
    representation.  The character "#" in pubsub-nodeid's and pubsub-itemid's
    MUST be escaped as %23.</p>

    <p>Since the scheme conforms to the URI generic syntax; URIs of this scheme
    are normalized and compared according to the algorithm defined in <cite>RFC
    3986</cite>, Section 6.</p>

    <p>The scheme and host are case-insensitive and normally provided in
    lowercase; all other components are compared in a case-sensitive manner.
    Characters other than those in the "reserved" set are equivalent to their
    percent-encoded octets (see <cite>RFC 3986</cite>, Section 2.1): the normal
    form is to not encode them.
    Non-ASCII characters can be encoded according to &UTF-8;, and then each
    octet of the corresponding UTF-8 sequence is percent-encoded to be
    represented as URI characters.</p>

    <p>If no NodeID and no ItemID is specified, the slash character after host
    is OPTIONAL. Likewise, if a NodeID but no ItemID is specified, the slash
    character after pubsub-nodeid is OPTIONAL. The normal form is to provide
    the slash character in either case.</p>
  </section1>

  <section1 topic="Semantics" anchor="semantics">
    <p>An 'xmpp.pubsub' URI designates a node within the context of a specific
    pubsub service, or an item within the scope of a node.
    A publish-subscribe service is an XMPP server or component that adheres
    to the protocol defined in <cite>XEP-0060</cite>.
    A node is a location to which information can be published and from which
    event notifications and/or payloads can be received. Nodes are uniquely
    identified by a NodeID within the context of a particular pubsub service.
    An item is an XML fragment which is published to a node, thereby generating
    an event. Items are uniquely identified by an ItemID within the scope of a
    node.</p>

    <p>An application that processes an 'xmpp.pubsub' URI reconstructs the
    encapsulated XMPP address, NodeID and optionally ItemID, connects to an
    appropriate XMPP server, and sends an appropriate XMPP "stanza" (XML
    fragment) with the NodeID and ItemID to the XMPP address.
    The set of possible operations is defined in <cite>XEP-0060</cite>.</p>

    <p>The query component provides a way to refer more specifically to
    data associated with the target. Possible values for URIs referring to
    nodes are: "meta-data" and "last-item".</p>

    <p>If an authority ("authxmpp") is given in the URI string, this indicates
    the user the application should connect as. Otherwise, the application
    should connect as the default user.</p>
  </section1>

  <section1 topic="Examples" anchor="examples">
    <example caption="A URI referring to a root node">
      <![CDATA[xmpp.pubsub:pubsub.shakespeare.lit/]]>
    </example>

    <example caption="A URI referring to a node">
      <![CDATA[xmpp.pubsub:pubsub.shakespeare.lit/princely_musings/]]>
    </example>

    <example caption="A URI referring to the meta-data of a node">
      <![CDATA[xmpp.pubsub:pubsub.shakespeare.lit/princely_musings/?meta-data]]>
    </example>

    <example caption="A URI referring to the last published item of a node">
      <![CDATA[xmpp.pubsub:pubsub.shakespeare.lit/princely_musings/?last-item]]>
    </example>

    <example caption="A URI referring to an item">
      <![CDATA[xmpp.pubsub:pubsub.shakespeare.lit/princely_musings/ae890ac52d0df67ed7cfdf51b644e901]]>
    </example>
  </section1>

  <section1 topic="Security Considerations" anchor="security">
    <p>TODO.</p>
  </section1>

  <section1 topic="IANA Considerations" anchor="iana">
    <p>This document requests the registration of the Uniform Resource
    Identifier (URI) scheme 'xmpp.pubsub' with &IANA;. The registration
    request complies with &rfc4395;.</p>

    <dl>
      <di>
        <dt>URI scheme name.</dt>
        <dd>xmpp.pubsub</dd>
      </di>
      <di>
        <dt>Status.</dt>
        <dd>Permanent</dd>
      </di>
      <di>
        <dt>URI scheme syntax.</dt>
        <dd>See the syntax section of &SELF;.</dd>
      </di>
      <di>
        <dt>URI scheme semantics.</dt>
        <dd>See the semantics section of &SELF;.</dd>
      </di>
      <di>
        <dt>Encoding considerations.</dt>
        <dd>See the syntax section of &SELF;.</dd>
      </di>
      <di>
        <dt>Applications/protocols that use this URI scheme name.</dt>
        <dd>The 'xmpp.pubsub' URI scheme is intended to be used by interfaces
        to an XMPP network that wish to interact with XMPP pubsub services
        and need to identify pubsub nodes within the context of these services
        as well as items in the scope of these nodes.</dd>
      </di>
      <di>
        <dt>Interoperability considerations.</dt>
        <dd>None.</dd>
      </di>
      <di>
        <dt>Security considerations.</dt>
        <dd>See the security considerations section of &SELF;.</dd>
      </di>
      <di>
        <dt>Contact.</dt>
        <dd>XSF</dd>
      </di>
      <di>
        <dt>Author/Change controller.</dt>
        <dd>XSF</dd>
      </di>
      <di>
        <dt>References.</dt>
        <dd>&SELF;</dd>
      </di>
    </dl>
  </section1>

  <section1 topic="XMPP Registrar Considerations" anchor="registrar">
    <p>No namespaces or parameters need to be registered with the &REGISTRAR;
    as a result of this document.</p>
  </section1>

  <section1 topic="Acknowledgements" anchor="acknowledgements">
    <p>Some text in this document was borrowed or adapted from <cite>RFC
    3986</cite>, <cite>RFC 5122</cite> and <cite>XEP-0060</cite>.</p>

    <p>This work was funded by Intel.</p>
  </section1>

</xep>