%ents; ]>
Stanza Headers and Internet Metadata This specification defines an XMPP protocol extension for representing non-address-related headers in an XML format that is appropriate for use in XMPP. While the protocol provides a flexible mechanism for representing many kinds of standard Internet metadata, a registry of values is defined to structure the possible range of headers, and the inital registration includes headers from email, HTTP, MIME, and SIP. &LEGALNOTICE; 0131 Draft Standards Track Standards XMPP Core XEP-0030 shim http://www.xmpp.org/schemas/shim.xsd &stpeter; &hildjj; 1.3pre1 in progress, last updated 2008-08-11 psa

Added Sequence header.

1.2 2006-07-12 psa

Added Urgency header from registry.

1.1 2005-08-19 psa

Added Date, DateTime, and Time headers conforming to profiles from XEP-0082; renamed Date header to RFC2822Date; added note about date-related headers; added headers from RFC 2413 (Dublin Core).

1.0 2004-10-22 psa

Per a vote of the Jabber Council, advanced status to Draft; also added more headers from RFC 2822 to the initial registry submission.

0.8 2004-09-29 psa

Specified service discovery usage; corrected examples; further specified security considerations.

0.7 2004-09-20 psa

Specified location of headers in IQ stanzas.

0.6 2004-07-06 psa

Added "Store" header.

0.5 2004-06-28 psa

Added "Distribute" header.

0.4 2004-05-27 psa

Added "Classification" header.

0.3 2004-05-10 psa

Added headers from RFCs 2045, 2616, 2617, and 3261 to initial registration.

0.2 2004-05-09 psa

Specified registry process; added headers from RFC 2822 to initial registration; defined "Created" and "TTL" headers.

0.1 2004-03-19 psa/jh

Initial version.

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 &xep0111;). Such information was formerly included in &xep0033;, but was removed from that specification when it was changed to focus on addressing information only. Therefore, this document defines a mechanism for encapsulating non-addressing "header" information about stanzas, including standard Internet metadata such as that defined by &rfc2045;, &rfc2616;, &rfc2617;, &rfc2822;, and &rfc3261;. Such information is encapsulated in a protocol extension qualified by the 'http://jabber.org/protocol/shim' namespace, where "SHIM" stands for "Stanza Headers and Internet Metadata".

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.)

In order to discover whether another entity supports this protocol, an entity MUST use &xep0030;.

]]> ... ... ]]>

It can be desirable (and, in some contexts, necessary) to determine if the intended recipient of an XML stanza supports a specific header (e.g., the "Classification" header) before sending information that may depend on that header. Therefore, implementations of this protocol MUST advertise which particular SHIM headers they support when queried via disco#info at the well-known service discovery node 'http://jabber.org/protocol/shim'.

]]> ... ... ]]>

The values of the 'var' attribute MUST be of the form "http://jabber.org/protocol/shim#header", where "header" is to be replaced with the name of the header as registered with the ®ISTRAR; (see below).

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: 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.

Neither, fair saint, if either thee dislike.
123456789@capulet.com
shakespeare,<xmpp/>
]]>

In accordance with &xmppcore;, 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/>).

2004-09-21T03:01:52Z
]]>

All public headers SHOULD be registered with the XMPP Registrar following the process specified in the XMPP Registrar Considerations section of this document. Many such headers are defined by other protocol specifications, such as RFCs 2045, 2616, 2617, 2822, and 3261; implementors MUST refer to those specifications for definition of the relevant headers.

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

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. Note: This header may be security-sensitive (see the Security Considerations for details).

The Date header is defined by RFC 2822 and therefore follows the date and time format defined by RFC 2822; while this header is thus useful for translating email messages into XMPP stanzas, it is not consistent with &xep0082;. 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 specified in XEP-0082.

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 &geoprivpol;. (The HTTP "Max-Forwards" header is not appropriate for this usage, since it defines proxy and gateway behavior rather than recipient behavior.) Note: This header may be security-sensitive (see the Security Considerations for details).

The Sequence header enables a sender to assign a sequence number to a message. This is most useful for notifications, web services interactions, and other automated processes.

39.755109 -104.997497
0
39.752799 -104.998871
1
39.751958 -105.00045
2
]]>

The Store header enables a sender to specify whether the stanza may be stored or archived by the recipient. The allowable values for this header are "true" and "false". If the sender specifies a value of "false", the recipient MUST NOT store the stanza or any information contained therein; if the sender specifies a value of "true", the recipient MAY store 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". Note: This header may be security-sensitive (see the Security Considerations for details).

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 &xep0079;. 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:

dnd in a meeting
2004-05-10T11:00Z
3600
]]>

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

... ...
2004-05-17T20:47Z
86400
]]>

It can be useful to specify that the information contained in a stanza is more or less time-sensitive (e.g., in order to help the recipient determine whether to attend to the information immediately or to delay attending to the information). Such is the function of the "Urgency" header, the value of which is "high", "medium", or "low". One use of the header is Sieve notifications (see &sievenotify;) sent via XMPP, as specified in &sievenotifyxmpp;.

Wherefore are thou?!?
high
]]>

Date formats differ widely. &xep0082; defines the Date, DateTime, and Time profiles of &iso8601;, which correspond to the Date, DateTime, and Time headers registered herein. The SHIM Date header also corresponds to the Date metadata element used in &DUBLINCORE; as specified in &rfc2413;.

However, many Internet standards use a different datetime format that ultimately derives from &rfc0822; as updated by &rfc1123;; specifically, that format is used by email (RFC 2822), the World Wide Web (RFC 2616), and the Session Initiation Protocol (RFC 3261). To map dates to and from these protocols, we define the SHIM RFC2822Date header.

In general, security considerations are the responsibility of the "using protocol".

Certain SHIM headers MAY be security-sensitive (e.g., the "Classification", "Distribute", and "Store" headers specified herein). If an entity plans to use such headers, it MUST determine whether the intended recipient supports both the SHIM protocol and the particular security-sensitive headers of interst, as described under Service Discovery; furthermore, an implementation MUST warn a human user (if any) before use if the security-sensitive headers of interest are not supported.

This document requires no interaction with &IANA;.

The XMPP Registrar includes 'http://jabber.org/protocol/shim' in its registry of protocol namespaces (see &SHIMHEADERS;).

The XMPP Registrar includes 'http://jabber.org/protocol/shim' in its registry of well-known Service Discovery nodes.

The XMPP Registrar maintains a registry of SHIM headers.

®PROCESS; the value of the 'name' attribute a natural-language description of the header the document in which this header is specified ]]>

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

Accept see RFC 2616 RFC 2616
Accept-Charset see RFC 2616 RFC 2616
Accept-Encoding see RFC 2616 RFC 2616
Accept-Language see RFC 2616 RFC 2616
Accept-Ranges see RFC 2616 RFC 2616
Age see RFC 2616 RFC 2616
Alert-Info see RFC 3261 RFC 3261
Allow see RFC 2616 RFC 2616
Authentication-Info see RFC 2617 RFC 2617
Cache-Control see RFC 2616 RFC 2616
Call-ID see RFC 3261 RFC 3261
Call-Info see RFC 3261 RFC 3261
Classification a level within a classification scheme XEP-0131
Comments see RFC 2822 RFC 2822
Connection see RFC 2616 RFC 2616
Contact see RFC 3261 RFC 3261
Content-Description see RFC 2045 RFC 2045
Content-Disposition see RFC 3261 RFC 3261
Content-Encoding see RFC 2616 RFC 2616
Content-ID see RFC 2045 RFC 2045
Content-Language see RFC 2616 RFC 2616
Content-Length see RFC 2616 RFC 2616
Content-Location see RFC 2616 RFC 2616
Content-MD5 see RFC 2616 RFC 2616
Content-Range see RFC 2616 RFC 2616
Content-Transfer-Encoding see RFC 2045 RFC 2045
Content-Type see RFC 2045 or RFC 2616 RFC 2045 or RFC 2616
Contributor an entity other than the primary Creator who helped to create a resource RFC 2413
Coverage the spatial or temporal characteristics of a resource RFC 2413
Created date and time of stanza creation in ISO 8601 format XEP-0131
Creator the person or organization responsible for creating the content of a resource RFC 2413
CSeq see RFC 3261 RFC 3261
Date a string that conforms to the Date profile specified in XEP-0082 XEP-0131
DateTime a string that conforms to the DateTime profile specified in XEP-0082 XEP-0131
Description a textual description of the content of a resource RFC 2413
Distribute whether or not the stanza may be further distributed XEP-0131
Error-Info see RFC 3261 RFC 3261
ETag see RFC 2616 RFC 2616
Expect see RFC 2616 RFC 2616
Expires see RFC 2616 RFC 2616
Format the data format of a resource RFC 2413
Host see RFC 2616 RFC 2616
Identifier a string or number used to identity a resource RFC 2413
If-Match see RFC 2616 RFC 2616
If-Modified-Since see RFC 2616 RFC 2616
If-None-Match see RFC 2616 RFC 2616
If-Range see RFC 2616 RFC 2616
If-Unmodified-Since see RFC 2616 RFC 2616
In-Reply-To see RFC 2822 RFC 2822
Keywords see RFC 2822 RFC 2822
Language the language in expressing the content of a resource RFC 2413
Last-Modified see RFC 2616 RFC 2616
Location see RFC 2616 RFC 2616
Max-Forwards see RFC 2616 RFC 2616
Message-ID see RFC 2822 RFC 2822
MIME-Version see RFC 2045 RFC 2045
Organization see RFC 3261 RFC 3261
Pragma see RFC 2616 RFC 2616
Priority see RFC 3261 RFC 3261
Proxy-Authenticate see RFC 2616 RFC 2616
Proxy-Authorization see RFC 2616 RFC 2616
Publisher the entity responsible for making a resource available RFC 2413
Range see RFC 2616 RFC 2616
Received see RFC 2822 RFC 2822
Record-Route see RFC 3261 RFC 3261
References see RFC 2822 RFC 2822
Referer see RFC 2616 RFC 2616
Relation the identifier of a second resource related to a primary resource RFC 2413
Reply-To see RFC 3261 RFC 3261
Require see RFC 3261 RFC 3261
Resent-Bcc see RFC 2822 RFC 2822
Resent-Cc see RFC 2822 RFC 2822
Resent-Date see RFC 2822 RFC 2822
Resent-From see RFC 2822 RFC 2822
Resent-Message-Id see RFC 2822 RFC 2822
Resent-Sender see RFC 2822 RFC 2822
Resent-To see RFC 2822 RFC 2822
Retry-After see RFC 2616 RFC 2616
Return-Path see RFC 2822 RFC 2822
RFC2822Date the datetime associated with an email message, SIP exchange, or HTTP request RFC 2822
Rights a rights management statement, identifier, or link RFC 2413
Route see RFC 3261 RFC 3261
Sender see RFC 2822 RFC 2822
Server see RFC 2616 RFC 2616
Source information about the original source of the present resource RFC 2413
Store whether or not the stanza may be stored or archived XEP-0131
Subject the human-readable topic of a message or resource RFC 2822 or RFC 2413
Supported see RFC 3261 RFC 3261
TE see RFC 2616 RFC 2616
Time a string that conforms to the Time profile specified in XEP-0082 XEP-0131
Timestamp see RFC 3261 RFC 3261
Title the name given to a resource RFC 2413
Trailer see RFC 2616 RFC 2616
Transfer-Encoding see RFC 2616 RFC 2616
TTL a time to live for the stanza, in seconds XEP-0131
Type the category of a resource RFC 2413
Unsupported see RFC 3261 RFC 3261
Upgrade see RFC 2616 RFC 2616
Urgency the time sensitivity of a stanza ("high", "medium", or "low") XEP-0131
User-Agent see RFC 2616 RFC 2616
Vary see RFC 2616 RFC 2616
Via see RFC 2616 RFC 2616
Warning see RFC 2616 RFC 2616
WWW-Authenticate see RFC 2616 RFC 2616
]]>
The protocol documented by this schema is defined in XEP-0131: http://www.xmpp.org/extensions/xep-0131.html ]]>