JEP-0131: Stanza Headers and Internet Metadata (SHIM)

This JEP defines a protocol extension for specifying headers about XMPP stanza content, including an XML representation of standard Internet metadata.


WARNING: This Standards-Track JEP is Experimental. Publication as a Jabber Enhancement Proposal does not imply approval of this proposal by the Jabber Software Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.


JEP Information

Status: Experimental
Type: Standards Track
Number: 0131
Version: 0.7
Last Updated: 2004-09-20
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: shim

Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Joe Hildebrand

Email: jhildebrand@jabber.com
JID: hildjj@jabber.org

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.


Table of Contents

1. Introduction
2. Requirements
3. Protocol
4. Header Definitions
4.1. Classification
4.2. Created
4.3. Distribute
4.4. Store
4.5. TTL
5. Security Considerations
6. IANA Considerations
7. Jabber Registrar Considerations
7.1. Protocol Namespaces
7.2. SHIM Headers Registry
7.2.1. Process
7.2.2. Initial Registration
8. XML Schema
Notes
Revision History


1. Introduction

In order to ensure proper processing by the recipient of an XML stanza, some Jabber protocols and other XMPP extensions may need to enable the sender to communicate non-addressing information about the stanza (this is especially true of protocols that translate from a foreign format to XMPP; a good example is TINS [1]). Such information was formerly included in Extended Stanza Addressing [2], but was removed from that specification when it was changed to focus on addressing information only. Therefore, this JEP defines a mechanism for encapsulating non-addressing "header" information about stanzas, including standard Internet metadata such as that defined by RFC 822 [3], RFC 2045 [4], RFC 2616 [5], and RFC 3261 [6].

2. Requirements

This protocol addresses the following requirements:

  1. Enable the inclusion of any header information
  2. Encapsulate all information in XML
  3. Ensure interoperability with existing non-XMPP header and metadata formats (HTTP, MIME, SIP, SMTP, etc.)

3. Protocol

In a fashion similar to the structure of Extended Stanza Addressing, headers for <message/> and <presence/> stanzas are contained in a <headers/> wrapper element qualified by the 'http://jabber.org/protocol/shim' namespace; each header is a child of this wrapper element, and is encapsulated via a <header/> element whose 'name' attribute identifies the header and whose XML character data specifies the relevant value: [7]

Example 1. A basic example

<message from='romeo@montague.net/orchard'
         to='juliet@capulet.com/balcony'>
  <body>Neither, fair saint, if either thee dislike.</body>
  <headers xmlns='http://jabber.org/protocol/shim'>
    <header name='in-reply-to'>123456789@capulet.com</header>
    <header name='keywords'>shakespeare,&lt;xmpp/&gt;</header>
  </headers>
</message>
  

In accordance with XMPP Core [8], an <iq/> stanza must not contain more than one non-error child element; this places constraints on the location of SHIM headers in the XML hierarchy. Specifically, the <headers/> wrapper element MUST NOT be a direct child of <iq/> and instead SHOULD be a grandchild of <iq/> and a direct child of the content-bearing child element of <iq/> (e.g., <query/>), not <error/>.

Example 2. An IQ example

<iq from='romeo@montague.net/orchard'
    to='juliet@capulet.com/balcony'
    id='ping1'>
  <query xmlns='jabber:iq:time'>
    <headers xmlns='http://jabber.org/protocol/shim'>
      <header name='Created'>2004-09-21T03:01:52Z</header>
    </headers>
  </query>
</iq>
  

4. Header Definitions

All allowable headers MUST be registered with the Jabber Registrar [9] following the process specified in the Jabber Registrar Considerations section of this document. Many such headers are defined by other protocol specifications, such as RFCs 822, 2045, 2616, and 3261; implementors MUST refer to those specifications for definition of the relevant headers.

This JEP defines several additional headers that may prove useful within Jabber protocols and other XMPP extensions, as specified in the following sections; further headers shall be registered with the Jabber Registrar, either directly or via definition in Jabber Enhancement Proposals.

4.1 Classification

The Classification header enables a sender or other entity to classify a stanza according to some classification scheme. The values of the XML character data contained within this header are out of scope for this document, since they are determined by the using application.

4.2 Created

The Date header is defined by RFC 822 and therefore follows the date and time format defined by RFC 822; while this header is thus useful for translating email messages into XMPP stanzas, it is not consistent with Jabber Date and Time Profiles [10]. Therefore we define the "Created" header, which specifies the date and time when a stanza was created by the originating entity, where the value conforms to the DateTime profile defined in JEP-0082.

4.3 Distribute

The Distribute header enables a sender to specify whether the stanza may be further distributed by the recipient to other entities on the network. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient MUST NOT further distribute the stanza or any information contained therein; if the sender specifies a value of "true", the recipient MAY further distribute the stanza or any information contained therein; if the value is anything other than "true" or "false" and the recipient does not understand the value, the recipient MUST assume the default value of "false". This header is semantically equivalent to the "Distribute" flag defined in Geopriv Policy [11]. (Note: The HTTP "Max-Forwards" header is not appropriate for this usage, since it defines proxy and gateway behavior rather than recipient behavior.)

4.4 Store

The Store header enables a sender to specify whether the stanza may be stored or archived by the recipient or an interim processor such as a router. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient or processor MUST NOT store the stanza; if the sender specifies a value of "true", the recipient or processor MAY store the stanza; if the value is anything other than "true" or "false" and the recipient does not understand the value, the recipient MUST assume the default value of "false".

4.5 TTL

It may be useful to specify that the information contained in a stanza is valid only for a limited period of time. Such is the function of the "TTL" header, the value of which is some number of seconds since the creation of the stanza. Note well that this header is purely informational and MUST NOT be used for routing or delivery of XML stanzas, since that function is already served by Advanced Message Processing [12]. A stanza that includes the "TTL" header SHOULD also include a "Created" header so that the recipient can properly process the stanza.

One situation in which both the "Created" and "TTL" headers might prove valuable is the broadcasting of structured presence information, such as a calendar-generated notification that a user will be in a meeting for the next hour:

Example 3. Time to Live for Presence Information

<presence>
  <show>dnd</status>
  <status>in a meeting</status>
  <headers xmlns='http://jabber.org/protocol/shim'>
    <header name='Created'>2004-05-10T11:00Z</header>
    <header name='TTL'>3600</header>
  </headers>
</message>
    

Another potential application is specifying a time to live for Service Discovery [13] results, which helps other entities know how long to cache such information:

Example 4. Time to Live for Disco Information

<iq from='example.com'
    id='some-id'
    to='example.org'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://jabber.org/protocol/amp'/>
    ...
  </query>
  <headers xmlns='http://jabber.org/protocol/shim'>
    <header name='Created'>2004-05-17T20:47Z</header>
    <header name='TTL'>86400</header>
  </headers>
</message>
    

5. Security Considerations

Security considerations are the responsibility of the using protocol.

6. IANA Considerations

This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [14].

7. Jabber Registrar Considerations

7.1 Protocol Namespaces

Upon advancement of this JEP to a status of Draft, the Jabber Registrar shall add the 'http://jabber.org/protocol/shim' namespace to its registry of protocol namespaces.

7.2 SHIM Headers Registry

Upon advancement of this JEP to a status of Draft, the Jabber Registrar shall create a registry of SHIM headers.

7.2.1 Process

In order to register new values in this registry, the registrant must define an XML fragment of the following form and either include it in the relevant Jabber Enhancement Proposal or send it to the email address <registrar@jabber.org>:

<header>
  <name>the value of the 'name' attribute</name>
  <desc>a natural-language description of the header</desc>
  <doc>the document in which this header is specified</doc>
</header>
      

The registrant may register more than one header at a time, each contained in a separate <header/> element.

7.2.2 Initial Registration

<header>
  <name>Accept</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Accept-Charset</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Accept-Encoding</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Accept-Language</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Accept-Ranges</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Age</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Alert-Info</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Allow</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Authentication-Info</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Cache-Control</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Call-ID</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Call-Info</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Classification</name>
  <desc>a level within a classification scheme</desc>
  <doc>JEP-0131</doc>
</header>

<header>
  <name>Connection</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Contact</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Content-Description</name>
  <desc>see RFC 2045</desc>
  <doc>RFC 2045</doc>
</header>

<header>
  <name>Content-Disposition</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Content-Encoding</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Content-ID</name>
  <desc>see RFC 2045</desc>
  <doc>RFC 2045</doc>
</header>

<header>
  <name>Content-Language</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Content-Length</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Content-Location</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Content-MD5</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Content-Range</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Content-Transfer-Encoding</name>
  <desc>see RFC 2045</desc>
  <doc>RFC 2045</doc>
</header>

<header>
  <name>Content-Type</name>
  <desc>see RFC 2045 or RFC 2616</desc>
  <doc>RFC 2045 or RFC 2616</doc>
</header>

<header>
  <name>Created</name>
  <desc>date and time of stanza creation in ISO 8601 format</desc>
  <doc>JEP-0131</doc>
</header>

<header>
  <name>CSeq</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Date</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>Distribute</name>
  <desc>whether or not the stanza may be further distributed</desc>
  <doc>JEP-0131</doc>
</header>

<header>
  <name>Error-Info</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>ETag</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Expect</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Expires</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Host</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>If-Match</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>If-Modified-Since</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>If-None-Match</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>If-Range</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>In-Reply-To</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>If-Unmodified-Since</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Keywords</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>Last-Modified</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Location</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Max-Forwards</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Message-ID</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>MIME-Version</name>
  <desc>see RFC 2045</desc>
  <doc>RFC 2045</doc>
</header>

<header>
  <name>Organization</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Pragma</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Priority</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Proxy-Authenticate</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Proxy-Authorization</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Range</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Record-Route</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>References</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>Referer</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Reply-To</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Require</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Retry-After</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Route</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Sender</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>Server</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Store</name>
  <desc>whether or not the stanza may be stored or archived</desc>
  <doc>JEP-0131</doc>
</header>

<header>
  <name>Subject</name>
  <desc>see RFC 822</desc>
  <doc>RFC 822</doc>
</header>

<header>
  <name>Supported</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>TE</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Timestamp</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Trailer</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Transfer-Encoding</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>TTL</name>
  <desc>a time to live for the stanza, in seconds</desc>
  <doc>JEP-0131</doc>
</header>

<header>
  <name>Unsupported</name>
  <desc>see RFC 3261</desc>
  <doc>RFC 3261</doc>
</header>

<header>
  <name>Upgrade</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>User-Agent</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Vary</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Via</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>Warning</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

<header>
  <name>WWW-Authenticate</name>
  <desc>see RFC 2616</desc>
  <doc>RFC 2616</doc>
</header>

      

8. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

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

  <xs:element name='headers'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='header' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='header'>
    <xs:complexType>
      <xs:simpleContent>
        <xs:extension base='xs:string'>
          <xs:attribute name='name' use='required'/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
  </xs:element>

</xs:schema>
  


Notes

1. JEP-0111: TINS <http://www.jabber.org/jeps/jep-0111.html>.

2. JEP-0033: Extended Stanza Addressing <http://www.jabber.org/jeps/jep-0033.html>.

3. RFC 822: Standard for the Format of ARPA Internet Text Messages <http://www.ietf.org/rfc/rfc0822.txt>.

4. RFC 2045: Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies <http://www.ietf.org/rfc/rfc2045.txt>.

5. RFC 2616: Hypertext Transport Protocol -- HTTP/1.1 <http://www.ietf.org/rfc/rfc2616.txt>.

6. RFC 3261: Session Initiation Protocol (SIP) <http://www.ietf.org/rfc/rfc3261.txt>.

7. Standard XML escaping rules apply to the XML character data, so that the characters < > ' " & MUST be escaped to &lt; &gt; &apos; &quot; &amp; respectively when translating from non-XML protocols (such as MIME and SIP) to SHIM, and the escaped sequences (e.g., &lt;) MUST be transformed to the equivalent non-escaped character (e.g., '<') when translating from SHIM to the non-XML protocol. Escaping and unescaping will normally be performed by a gateway that translates between XMPP and a foreign protocol such as MIME or SIP.

8. XMPP Core <http://www.jabber.org/ietf/> (Proposed Standard, RFC number to follow).

9. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

10. JEP-0082: Jabber Date and Time Profiles <http://www.jabber.org/jeps/jep-0082.html>.

11. Geopriv Policy <http://www.ietf.org/internet-drafts/draft-ietf-geopriv-policy-01.txt>. Work in progress.

12. JEP-0079: Advanced Message Processing <http://www.jabber.org/jeps/jep-0079.html>.

13. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

14. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.


Revision History

Version 0.7 (2004-09-20)

Specified location of headers in IQ stanzas. (psa)

Version 0.6 (2004-07-06)

Added "Store" header. (psa)

Version 0.5 (2004-06-28)

Added "Distribute" header. (psa)

Version 0.4 (2004-05-27)

Added "Classification" header. (psa)

Version 0.3 (2004-05-10)

Added headers from RFCs 2045, 2616, and 3261 to initial registration. (psa)

Version 0.2 (2004-05-09)

Specified registry process; added headers from RFC 822 to initial registration; defined "Created" and "TTL" headers. (psa)

Version 0.1 (2004-03-19)

Initial version. (psa)


END