XEP-0227: Portable Import/Export Format for XMPP-IM Servers

This document specifies a file format for importing and exporting user data to and from XMPP-IM servers.


WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards 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.


Document Information

Series: XEP
Number: 0227
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.1
Last Updated: 2007-08-08
Approving Body: XMPP Council
Dependencies: XMPP IM, XEP-0049, XEP-0054
Supersedes: None
Superseded By: None
Short Name: TO BE ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Portable Import/Export Format for XMPP-IM Servers (XEP-0227)>

Author Information

Magnus Henoch

Email: henoch@dtek.chalmers.se
JabberID: legoscia@jabber.cd.chalmers.se

Legal Notice

This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).

Discussion Venue

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

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

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


Table of Contents


1. Introduction
2. Requirements
3. Glossary
4. File format
    4.1. Hosts
    4.2. Users
    4.3. Rosters
    4.4. Offline Messages
    4.5. Private XML Storage
    4.6. vCards
5. Security Considerations
6. IANA Considerations
7. XMPP Registrar Considerations
    7.1. Protocol Namespaces
8. XML Schema
Notes
Revision History


1. Introduction

Different implementations of XMPP-IM servers store user data in various ways, and many implementations have more than one storage format. This leads to problems when a server administrator wants to switch to another implementation or storage format -- the implementation is as likely as not to have an import mechanism that can read the user data in its current form. This document attempts to solve that problem by defining a common file format for import and export of user data in XMPP-IM servers.

2. Requirements

The following constraints are imposed on this standard:

3. Glossary

4. File format

Data is contained in a single XML file, whose root element is <server-data/> qualified by the 'http://www.xmpp.org/extensions/xep-0227.html#ns' namespace (see Protocol Namespaces regarding issuance of one or more permanent namespaces).

Example 1. The root element

<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  [ ... ]
</server-data>

At any point in the file, an exporting server may put elements qualified by a namespace not mentioned in this specification. The exported data SHOULD be meaningful without the extensions. An importing server that encounters a namespace that it doesn't understand, or otherwise is unable to import all given data, SHOULD ignore the unknown data, SHOULD notify the operator, and MAY offer to terminate the process.

4.1 Hosts

The child elements of the <server-data/> elements are <host/> elements. Each <host/> element describes a virtual host, and has a 'jid' attribute that contains its JID.

An importing server MAY automatically adjust its list of virtual hosts to fit the ones present in the data being imported. If it does not, it SHOULD notify the operator about any mismatch.

Example 2. The host element

 
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  <host jid='capulet.com'>
    [ ... ]
  </host>
  <host jid='montague.net'>
    [ ... ]
  </host>
</server-data> 

4.2 Users

Each user is represented by a <user/> element under the <host/> element. The <user/> element MUST have a 'name' attribute, which contains the node part of the user's JID, and SHOULD have a 'password' attribute, which contains the user's password.

Example 3. The user element

<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  <host jid='capulet.com'>
    <user name='juliet' password='s3crEt'>
      [ ... ]
    </user>
  </host>
  <host jid='montague.net'>
    <user name='romeo' password='iLuvJuLi3T'>
      [ ... ]
    </user>
  </host>
</server-data> 

4.3 Rosters

Each <user/> element SHOULD contain the user's roster in the form of a <query/> element qualified by the 'jabber:iq:roster' namespace. This element contains the user's roster in the same format as when retrieving the roster from the server, as described in section 7.3 of XMPP IM [1].

Example 4. The roster

<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  <host jid='capulet.com'>
    <user name='juliet' password='s3crEt'>
      <query xmlns='jabber:iq:roster'>
        <item jid='romeo@montague.net'
              name='Romeo'
              subscription='both'>
          <group>Friends</group>
        </item>
      </query>
    </user>
  </host>
</server-data> 

4.4 Offline Messages

If the exporting server stores messages received while the user was offline, it SHOULD include an <offline-messages/> element as a child of the <user/> element. This element contains all the stored messages to the user, if any, as <message/> elements qualified by the 'jabber:client' namespace, starting with the oldest.

Example 5. Offline messages

<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  <host jid='capulet.com'>
    <user name='juliet' password='s3crEt'>
      <offline-messages>
        <message xmlns='jabber:client'
	         from='romeo@montague.net/orchard'
	         to='juliet@capulet.com/balcony'
		 type='chat'>
	  <body>Neither, fair saint, if either thee dislike.</body>
	  <delay xmlns='urn:xmpp:delay'
	         from='capulet.com'
		 stamp='1469-07-21T00:32:29Z'>
	    Offline Storage
	  </delay>
	</message>
      </offline-messages>
    </user>
  </host>
</server-data> 

4.5 Private XML Storage

Private data stored by the server as specified in Private XML Storage [2] is represented in this format by including a <query/> element qualified by the 'jabber:iq:private' namespace as a child of the <user/> element. This <query/> element in turn contains all elements saved in private XML storage.

Example 6. Private XML Storage

<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  <host jid='shakespeare.lit'>
    <user name='hamlet' password='2b0Rnot2B'>
      <query xmlns="jabber:iq:private">
	<exodus xmlns="exodus:prefs">
	  <defaultnick>Hamlet</defaultnick>
	</exodus>
      </query>
    </user>
  </host>
</server-data> 

4.6 vCards

By vcard-temp [3], users can store vCards on the server. In this specification, vCards are child elements of the <user/> element, namely a <vCard/> element qualified by the 'vcard-temp' namespace.

Example 7. vCards

<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
  <host jid='capulet.com'>
    <user name='juliet' password='s3crEt'>
      <vCard xmlns='vcard-temp'>
        <FN>Juliet Capulet</FN>
      <vCard>
    </user>
  </host>
</server-data> 

5. Security Considerations

Exported data files are to be handled with care, since they contain data that users expect to be protected, in particular passwords. An exporting server SHOULD make sure that the generated file is not accessible to unauthorized persons, e.g. by enforcing strict file permissions.

6. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA).

7. XMPP Registrar Considerations

7.1 Protocol Namespaces

Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0227.html#ns"; upon advancement of this specification, the XMPP Registrar [4] shall issue a permanent namespace in accordance with the process defined in Section 4 of XMPP Registrar Function [5].

8. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://www.xmpp.org/extensions/xep-0227.html#ns'
    xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'
    elementFormDefault='qualified'>

  <xs:element name='server-data'>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref='host' maxOccurs='unbounded'/>
        <xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

  <xs:element name='host'>
    <xs:complexType>
      <xs:sequence>
	<xs:element ref='user' maxOccurs='unbounded'/>
	<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='jid' type='xs:string' use='required'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='user'>
    <xs:complexType>
      <xs:sequence>
	<xs:element ref='offline-messages' minOccurs='0' maxOccurs='1'/>
	<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
      <xs:attribute name='name' type='xs:string' use='required'/>
      <xs:attribute name='password' type='xs:string' use='optional'/>
    </xs:complexType>
  </xs:element>

  <xs:element name='offline-messages'>
    <xs:complexType>
      <xs:sequence>
	<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

</xs:schema>
  

Notes

1. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.

2. XEP-0049: Private XML Storage <http://www.xmpp.org/extensions/xep-0049.html>.

3. XEP-0054: vcard-temp <http://www.xmpp.org/extensions/xep-0054.html>.

4. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.

5. XEP-0053: XMPP Registrar Function <http://www.xmpp.org/extensions/xep-0053.html>.


Revision History

Version 0.1 (2007-08-08)

Initial published version.

(psa)

Version 0.0.1 (2007-07-27)

Initial version.

(mh)

END