XEP-0322: Efficient XML Interchange (EXI) Format

Abstract:This specification describes how EXI compression can be used in XMPP networks.
Author:Peter Waher
Copyright:© 1999 - 2013 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Experimental
Type:Standards Track
Version:0.1
Last Updated:2013-04-16

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 are advised to carefully consider whether it is appropriate to deploy implementations of this protocol before it advances to a status of Draft.


Table of Contents


1. Introduction
2. Use Cases
    2.1. Detecting support
    2.2. Invalid setup
    2.3. Proposing compression parameters
    2.4. Uploading new schema files
    2.5. Uploading compressed schema files
    2.6. Downloading new schema files on server
    2.7. Start compression
3. Implementation Notes
    3.1. EXI options
    3.2. Transmission of EXI bodies and Session-wide Buffers
    3.3. Preserving prefixes
    3.4. Networks containing clients having limited memory
    3.5. Caching schema files
    3.6. Uploading vs. Downloading schemas
    3.7. Server decompression and recompression vs. binary forwarding
4. Security Considerations
5. IANA Considerations
6. XMPP Registrar Considerations
7. XML Schema
8. Acknowledgements

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Introduction

The Efficient XML Interchange (EXI) Format [1] is an efficient way to compress XML documents and XML fragments. This document provides information on how EXI can be used in XMPP streams to efficiently compress data transmitted between the server and the client. For certain applications (like applications in sensor networks) EXI is a vital component, decreasing packet size enabling sensors with limited memory to communicate efficiently. The strong support in EXI for generating efficient stubcodes is also vital to build efficient code in constrained devices.

Activating EXI compression requires a handshake to take place prior, where the server and client agree on a set of parameters. Some of these parameters may increase the compression ratio, at the cost of processing power and readability. These parameters include:

These parameters will be discussed in greater depth in the following sections. There are also default values that can be used to commence evaluating EXI compression.

The single most important property to agree on however, is the set of schemas to use during EXI compression. EXI compresses XML much more efficiently if schemas exist describing the format of the expected XML. Since the server is not supposed to know all possible XML schemas, a mechanism is provided in this document whereby schemas can be interchanged, so that the server can adapt its compression to the needs of the client.

2. Use Cases

2.1 Detecting support

This XEP is based on Stream Compression [2]. When the client connects to the XMPP Server, it will receive a list of features supported by the server:

Example 1. Search Features

                
    <stream:features>
        <starttls xmlns='urn:ietf:params:xml:ns:xmpp-tls'/>
        <compression xmlns='http://jabber.org/features/compress'>
            <method>zlib</method>
            <method>lzw</method>
            <method>exi</method>
        </compression>
    </stream:features>
            

Support for EXI compression is detected by the existence of the exi compression method in the features stanza.

2.2 Invalid setup

If the client attempts to activate an EXI stream at this point, before the negotiation of EXI properties has been performed, the server must respond with a setup-failed response.

Example 2. Invalid setup

                
    <compress xmlns='http://jabber.org/protocol/compress'>
        <method>exi</method>
    </compress>
 
    <failure xmlns='http://jabber.org/protocol/compress'>
        <setup-failed/>
    </failure>
            

2.3 Proposing compression parameters

When the client decides to activate EXI compression, it sends a setup stanza containing parameter proposals to the server as follows:

Example 3. Proposing compression parameters

                
    <setup xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
        <schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
        <schema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
    </setup>
            

The server in turn responds with a setupResponse stanza containing the parameters it can accept, based on the initial values provided by the client. Any buffer sizes, etc., may have been changed, but only lowered, never raised.

Example 4. Unable to accommodate parameters

                
    <setupResponse xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true'
                   blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
        <schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
        <missingSchema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
    </setupResponse>
            

Note: Schema files are identified using three properties: Its target namespace, its byte size and its MD5 hash. The MD5 hash provides a way to detect small changes in the file, even if the byte size and namespace are the same.

Schema files that the server does not have (based on namespace, byte size and MD5 hash) are marked with the missingSchema element instead of the normal schema element.

At this point the client can choose to abort the EXI enablement sequence, if it cannot accommodate itself with the proposed parameter settings provided by the server. The XMPP session will continue to work in its current state. Aborting does not require taking further action from the client.

2.4 Uploading new schema files

If the server lacks information about a schema file, it is specified in the response through the missingSchema elements. At this point, the client can either choose to accept that these schema files are not available, making compression less efficient, or choose to upload the missing schema files to the server. Of course, uploading schema files would require the device to have sufficient buffers and memory to store and upload the schema files in the first place. (If it is not possible to upload the schema files, consideration should be given to installing the schema files manually at the server.)

To upload a schema file, the client simply sends the schema file using an uploadSchema element, as follows:

Example 5. Uploading schema file

                
    <uploadSchema xmlns='http://jabber.org/protocol/compress/exi' contentType='Text'>
        PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4NCjx4czpzY2hlbWENCiAgICB4
        bWxuczp4cz0naHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEnDQogICAgdGFyZ2V0TmFt
        ZXNwYWNlPSd1cm46eG1wcDpzbjpwcm92aXNpb25pbmcnDQogICAgeG1sbnM9J3Vybjp4bXBwOnNu
        
        ...
        
        dmlsZWdlJz4NCgkJPHhzOmF0dHJpYnV0ZSBuYW1lPSdpZCcgdHlwZT0nUHJpdmlsZWdlSWQnIHVz
        ZT0ncmVxdWlyZWQnLz4NCgk8L3hzOmNvbXBsZXhUeXBlPg0KIA0KPC94czpzY2hlbWE+DQo=
    </uploadSchema>
            

The schema itself is sent using base64 encoding to the server. This is to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The server then computes the target namespace, byte size and MD5 Hash from the sent schema file.

If the client desires, it can test the EXI setup again. This is optional, but can be used to test that uploading the schema files, and any new property values are accepted by the server.

Example 6. Testing newly uploaded schema files

                
    <setup xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100'>
        <schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
        <schema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
    </setup>
            

And the server should then respond:

Example 7. Agreement between client and server

                
    <setupResponse xmlns='http://jabber.org/protocol/compress/exi' version='1' strict='true' 
                   blockSize='1024' valueMaxLength='32' valuePartitionCapacity='100' agreement='true'>
        <schema ns='urn:xmpp:sn' bytes='8092' md5Hash='18829242ca7a72a552a7e15af5b9e44d'/>
        <schema ns='urn:xmpp:sn:provisioning' bytes='6303' md5Hash='e5301add51f3b24c15a71256b53daa47'/>
    </setupResponse>
            

Note the agreement attribute in the response this time. The server must set this attribute to true if it agrees with the proposal from the client. The client in turn can check this attribute as a quick way to check if agreement exists.

2.5 Uploading compressed schema files

The uploadSchema command has an optional attribute called contentType that can be used to send different types of documents to the server. This is not a MIME content type, but an enumeration with the following options:

Table 1: contentType values

Value Description
Text The schema is sent as plain text. If no encoding is provided in the XML header of the schema file, UTF-8 encoding is assumed. This is the default value.
ExiBody The schema file is sent as an EXI compressed file, but only the body is sent. *
ExiDocument The schema file is sent as an EXI compressed file. The entire file, including Exi header is provided. *

(*) These options assume the following set of default EXI options are used. It is assumed the XMPP server has more capabilities than the client, so the following set of options must be supported by the XMPP server. The schema files can be precompressed and stored as binary files on the client for easier transmission.

Table 2: Default EXI options

Option Default value
Version 1
alignment bit-packed
compression false
strict false
fragment false
preserve all false
selfContained false
schemaId No schema
datatypeRepresentationMap No map
blockSize 1000000 (one million)
valueMaxLength unbounded
valuePartitionCapacity unbounded

Since EXI compression does not perserve the extact binary representation of the schema file (for instance it doesn't preserve white space), the server cannot correctly compute byte size and an MD5 hash for the file. Therefore, the client needs to provide this information in the uploadSchema command using the bytes and md5Hash attributes. They are mandatory in case EXI compressed schema files are uploaded to the server. Also note that the byte length and MD5 Hash should be computed on the original XML Schema file, not the compressed or decompressed version.

2.6 Downloading new schema files on server

As an alternative to uploading a schema file to the server, the client can ask the server to download a schema file by itself. This is done using the downloadSchema command, as follows:

Example 8. Downloading new schema files on server

                
    <downloadSchema xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd'/>
            

The server tries to download the schema by itself, and then computes the target namespace, byte size and MD5 Hash from the downloaded schema.

When the schema has been downloaded, the following successful download response is returned:

Example 9. Schema successfully downloaded

                
    <downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='true'/>
            

If an HTTP error occurred while trying to download the schema, a response as follows is returned:

Example 10. HTTP Error

                
    <downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
        <httpError code='404' message='NotFound'/>
    </downloadSchemaResponse>
            

If the URL could not be resolved, the following response is returned:

Example 11. Invalid URL

                
    <downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='urk://example.com/schema.xsd' result='false'>
        <invalidUrl message='Unrecognized schema.'/>
    </downloadSchemaResponse>
            

If a timeout occurred during the download attempt, the following response is returned:

Example 12. Timeout

                
    <downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
        <timeout message='No response returned.'/>
    </downloadSchemaResponse>
            

If the url points to something that is not a schema, the following response is returned:

Example 13. Invalid Content Type

                
    <downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
        <invalidContentType contentTypeReturned='text/html'/>
    </downloadSchemaResponse>
            

If an error occurs that is unforeseen by this specification, the server can simply respond with a generic error message, as follows:

Example 14. Other types of errors

                
    <downloadSchemaResponse xmlns='http://jabber.org/protocol/compress/exi' url='http://schemavault.se/compress/sn/provisioning.xsd' result='false'>
        <error message='No free space left.'/>
    </downloadSchemaResponse>
            

Note: Downloading a schema, might download a version which does not correspond to the desired version of the schema. It's more important in this case so the client checks that the server actually has the version of the schema required by the client.

2.7 Start compression

When EXI option negotiation has been completed, the client can tell the server that it is ready to start compression. It does this using the normal compress stanza, as follows:

Example 15.

                
    <compress xmlns='http://jabber.org/protocol/compress'>
        <method>exi</method>
    </compress>
            

The server now has the necessary knowledge on how the EXI engine should be configured for the current session and it responds as follows:

Example 16. Compression accepted

                
    <compressed xmlns='http://jabber.org/protocol/compress'/>
            

When the client receives acknowledgement that the compression method has been accepted, it restarts the stream, as explained in XEP 0138, except that it must not resend the <stream> start element sequence. Similarly, the client must not send a </stream> element when closing the session. Closing the connection is sufficient.

3. Implementation Notes

3.1 EXI options

The following segment is taken from the EXI specification. It describes the different EXI options that need to be negotiated before enabling EXI.

The alignment option is used to control the alignment of event codes and content items. The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options document, respectively. When the value of compression option is set to true, alignment of the EXI Body is governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment" element MUST NOT appear in an EXI options document when the "compression" element is present.

The alignment option value bit-packed indicates that the event codes and associated content are packed in bits without any padding in-between.

The alignment option value byte-alignment indicates that the event codes and associated content are aligned on byte boundaries. While byte-alignment generally results in EXI streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a help in some use cases that involve frequent copying of large arrays of scalar data directly out of the stream. It can also make it possible to work with data in-place and can make it easier to debug encoded data by allowing items on aligned boundaries to be easily located in the stream.

The alignment option value pre-compression indicates that all steps involved in compression (see section 9. EXI Compression) are to be done with the exception of the final step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a duplicate compression step when compression capability is built into the transport protocol. In this case, pre-compression just prepares the stream for later compression.

The compression option is a Boolean used to increase compactness using additional computational resources. The default value "false" is assumed when the "compression" element is absent in the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes and associated content are compressed according to 9. EXI Compression regardless of the alignment option value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the "alignment" element is present.

The strict option is a Boolean used to increase compactness by using a strict interpretation of the schemas and omitting preservation of certain items, such as comments, processing instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and schema-informed element and type grammars are restricted to only permit items declared in the schemas. A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same options document.

The preserve option is a set of Booleans that can be set independently to each enable or disable a share of the format's capacity determining whether or how certain information items can be preserved in the EXI stream. Section 6.3 Fidelity Options describes the set of information items affected by the preserve option. The presence of "dtd", "prefixes", "lexicalValues", "comments" and "pis" in the EXI Options document each turns on fidelity options Preserve.comments, Preserve.pis, Preserve.dtd, Preserve.prefixes and Preserve.lexicalValues whereas the absence denotes turning each off. The elements "dtd", "prefixes", "comments" and "pis" MUST NOT appear in an EXI options document when the "strict" element is present in the same options document. The element "lexicalValues", on the other hand, is permitted to occur in the presence of "strict" element.

The selfContained option is a Boolean used to enable the use of self-contained elements in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body, allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI options document when one of "compression", "pre-compression" or "strict" elements are present in the same options document. The default value "false" is assumed when the "selfContained" element is absent from the EXI Options document whereas its presence denotes the value "true".

The datatypeRepresentationMap option specifies an alternate set of datatype representations for typed values in the EXI body as described in 7.4 Datatype Representation Map. When there are no "datatypeRepresentationMap" elements in the EXI Options document, no Datatype Representation Map is used for processing the EXI body. This option does not take effect when the value of the Preserve.lexicalValues fidelity option is true (see 6.3 Fidelity Options), or when the EXI stream is a schema-less EXI stream.

The blockSize option specifies the block size used for EXI compression. When the "blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used. The default blockSize is intentionally large but can be reduced for processing large documents on devices with limited memory.

The valueMaxLength option specifies the maximum length of value content items to be considered for addition to the string table. The default value "unbounded" is assumed when the "valueMaxLength" element is absent in the EXI Options document.

The valuePartitionCapacity option specifies the maximum number of value content items in the string table at any given time. The default value "unbounded" is assumed when the "valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions Optimized for Frequent use of String Literals specifies the behavior of the string table when this capacity is reached.

The sessionWideBuffers controls buffer and string table life time. If set to true, all buffers, string tables, etc. will be maintained during the entire session. This may improve performance during time since strings can be omitted in the compressed binary stream, but it might also in some cases degrade performance since more options are available in the tables, requiring more bits to encode strings. The default value is false, meaning that buffers, string tables, etc., are cleared between each stanza. (This option is EXI/XMPP specific.)

3.2 Transmission of EXI bodies and Session-wide Buffers

The transmission of EXI-compressed stanzas takes the form of a sequence of EXI bodies. In order for the recipient to be able to correctly interpret these incoming EXI bodies, the sender is required to flush any pending bits at the end of the last End Document (ED) event for each stanza and then send any pending bytes available in the output buffer. Since this makes sure each EXI body starts at an even byte boundary, it permits the recipient to decompress the body into an XML stanza.

Therefore, each stanza sent on the stream, must be compressed separately, reusing the same options as used by the stream. (Options are not sent on the stream, only the generated EXI bodies).

Compression of the stanza must be done in document mode, not fragment mode, including the Start Document (SD) and End Document (ED) events. If there are unwritten bits pending after the last End Document (ED) event (after the end of the stanza), Zero-bits are written until a byte boundary is created. The receptor must ignore bits in the last byte after the last End Document event has been received.

During setup of the EXI compression engine, the client can choose if buffers are to be reused between stanzas, or cleared between each stanza. This is done using the EXI over XMPP specific option sessionWideBuffers, which is false by default, meaning buffers and string tables are cleared between each stanza.

There may be cases where maintaining buffers and string tables throughout the session is preferrable. Since strings are already available in the buffers, they don't need to be output in the stream the first time they appear in a stanza. However, the number of strings in tables increase, and so does the number of bits required to encode them. Depending on what type of communication is performed, this option might give better results one way or another. If the same type of message is always sent, maintaining string buffers may be more efficient. But if the client sends many many different types of messages, clearing buffers may be more efficient.

Note that the stream of EXI bodies is indefinite. It only stops when the session is closed, i.e. when the socket connection is dropped. Therefore, the buffers can grow indefinitely unless control is maintained on what types of messages are sent, their contents (specifically string values), and to whom they are sent (JIDs being strings). All string tables and buffers must be cleared when a connection is lost.

Note also that if you want the option to enter a session in the middle of the flow to listen to the communication, you need to clear tables and buffers between each stanza, or you will not be able to decode the binary stream appropriately.

3.3 Preserving prefixes

Normally, prefixes are not preserved during EXI compression and decompression. If the communicating parties (sending client, XMPP server(s) and receiving clients) interpret incoming stanzas and content according to namespace, this should be sufficient. However, some implementations do not check namespaces, but prefix names used. In such cases, all communicating parties are required to enable the preserve prefixes option during negotionating.

Note: It is not sufficient that one party enable this option. Both sender and received are required to enable this option, or prefix names will be lost in the transmission.

Note also, that preserving prefix names result in less efficient compression. Therefore, all clients implementing EXI compression should strive to parse incoming XML based on namespace, not prefix name.

3.4 Networks containing clients having limited memory

To successfully implement a network with clients having limited memory, such as sensor networks, care should be taken to make sure necessary schema files are preinstalled on the server, to avoid the necessity to upload schema files from the clients. Clients with limited memory might be unable to perform this task.

An alternative may be to install a richer client, that can upload the schema files to the server dynamically, and installing it into the network. Any client uploading a schema file, will make that schema file available for EXI compression to any other client in the network.

3.5 Caching schema files

Schema files uploaded to the server should be cached on the server in some kind of schema repository. If memory is limited on the server, schema files should be sorted by last access. Schema files with the oldest last access timestamp could be removed to maintain the cache within an approved cache size.

Note that schema files have three keys: Target namespace, byte size and MD5 Hash. Multiple versions of a schema file may exist (that is, with the same target namespace but different byte sizes or MD5 hash codes). Note also, that for any practical purpose, schema files can be stored using only the MD5 hash as a key, since it is highly improbable that two different schema files will have the same MD5 hash (unless consciously created that way). MD5 hash values are always in lower case.

3.6 Uploading vs. Downloading schemas

When the server lacks information about a given XML schema, the client has two options for updating the server. Either it uploads the schema, or it asks the server to download one.

Uploading a schema has the advantage, that the client knows exactly the version that the server requires. It has the disadvantage, that the client needs to store the schema and send a possible large schema to the server. If EXI is used because the device has limited memory, uploading a schema might not be an option.

Downloading a schema has the advantage, that size of schema does not matter. The disadvantage is that asynchronous errors might occur, so the client needs to pay attention to the responses returned by the server when downloading schemas. Also, downloading a schema, might download a version which does not correspond to the desired version of the schema. So, it's more important in this case that the client checks that the server actually has the version of the schema required by the client.

3.7 Server decompression and recompression vs. binary forwarding

If two XMPP clients communicate with each other through an XMPP server, and both clients use EXI compression, the server must only forward binary packets if both EXI compressed channels have exactly the same setup. If any parameter is different, the server MUST always recompress packets sent through it.

Since the server always needs to decompress incoming EXI compressed packets to decode headers, omitting the compression part might save the server some processing power, but not all. Note that, in some networks it might be common using similar compression settings, while in others different compression settings are most common.

4. Security Considerations

Note that EXI compressed information, even though it is hard to decode by humans, is by no means encrypted. If sensitive data is to be sent over an EXI compressed channel, encryption should be considered as well.

5. IANA Considerations

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

6. XMPP Registrar Considerations

REQUIRED.

7. XML Schema

            
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://jabber.org/protocol/compress/exi'
    xmlns='http://jabber.org/protocol/compress/exi'
    elementFormDefault='qualified'>
    
    <xs:element name='setup' type='Setup'/>
    <xs:element name='setupResponse' type='SetupResponse'/>
 
    <xs:complexType name='Setup'>
        <xs:choice minOccurs='0' maxOccurs='unbounded'>
            <xs:element name='schema' type='Schema'/>
            <xs:element name='datatypeRepresentationMap' type='DatatypeRepresentationMap'/>
        </xs:choice>
        <xs:attributeGroup ref='Options'/>
    </xs:complexType>
 
    <xs:complexType name='SetupResponse'>
        <xs:complexContent>
            <xs:extension base='Setup'>
                <xs:choice minOccurs='0' maxOccurs='unbounded'>
                    <xs:element name='missingSchema' type='Schema'/>
                </xs:choice>
                <xs:attribute name='agreement' type='xs:boolean' use='optional' default='false'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
    <xs:complexType name='Schema'>
        <xs:attribute name='ns' type='xs:string' use='required'/>
        <xs:attribute name='bytes' type='xs:positiveInteger' use='required'/>
        <xs:attribute name='md5Hash' type='MD5Hash' use='required'/>
    </xs:complexType>
 
    <xs:complexType name='DatatypeRepresentationMap'>
        <xs:attribute name='type' type='xs:string' use='required'/>
        <xs:attribute name='representAs' type='xs:string' use='required'/>
    </xs:complexType>
 
    <xs:attributeGroup name='Options'>
        <xs:attribute name='version' type='xs:positiveInteger' use='optional' default='1'/>
        <xs:attribute name='alignment' type='Alignment' use='optional' default='bit-packed'>
            <xs:annotation>
                <xs:documentation>The alignment option is used to control the alignment of event codes and content items. 
                The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value 
                assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment 
                and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options 
                document, respectively. When the value of compression option is set to true, alignment of the EXI Body is 
                governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment" 
                element MUST NOT appear in an EXI options document when the "compression" element is present.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='compression' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>The compression option is a Boolean used to increase compactness using additional 
                computational resources. The default value "false" is assumed when the "compression" element is absent in 
                the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes 
                and associated content are compressed according to 9. EXI Compression regardless of the alignment option 
                value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the 
                "alignment" element is present.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='strict' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>The strict option is a Boolean used to increase compactness by using a strict 
                interpretation of the schemas and omitting preservation of certain items, such as comments, processing 
                instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is 
                absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those 
                productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and 
                schema-informed element and type grammars are restricted to only permit items declared in the schemas. 
                A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions 
                consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document 
                when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same 
                options document.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='preserveComments' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>Comments are preserved. Must not be used together with the strict option.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='preservePIs' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>Processing instructions are preserved. Must not be used together with the strict 
                option.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='preserveDTD' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>DTD is preserved. Must not be used together with the strict option.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='preservePrefixes' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>Prefixes are preserved. Must not be used together with the strict option.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='preserveLexical' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>Lexical form of element and attribute values can be preserved in value content items. 
                Can be used together with the strict option.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='selfContained' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>The selfContained option is a Boolean used to enable the use of self-contained elements 
                in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body, 
                allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI 
                options document when one of "compression", "pre-compression" or "strict" elements are present in the 
                same options document. The default value "false" is assumed when the "selfContained" element is absent 
                from the EXI Options document whereas its presence denotes the value "true".</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='blockSize' type='xs:positiveInteger' use='optional' default='1000000'>
            <xs:annotation>
                <xs:documentation>The blockSize option specifies the block size used for EXI compression. When the 
                "blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used. 
                The default blockSize is intentionally large but can be reduced for processing large documents on 
                devices with limited memory.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='valueMaxLength' type='xs:positiveInteger' use='optional'>
            <xs:annotation>
                <xs:documentation>The valueMaxLength option specifies the maximum length of value content items to be 
                considered for addition to the string table. The default value "unbounded" is assumed when the 
                "valueMaxLength" element is absent in the EXI Options document.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='valuePartitionCapacity' type='xs:positiveInteger' use='optional'>
            <xs:annotation>
                <xs:documentation>The valuePartitionCapacity option specifies the maximum number of value content 
                items in the string table at any given time. The default value "unbounded" is assumed when the 
                "valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions 
                Optimized for Frequent use of String Literals specifies the behavior of the string table when this 
                capacity is reached.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
        <xs:attribute name='sessionWideBuffers' type='xs:boolean' use='optional' default='false'>
            <xs:annotation>
                <xs:documentation>If set to true, all buffers, string tables, etc. will be maintained during the 
                entire session. This may improve performance during time since strings can be omitted in the 
                compressed binary stream, but it might also in some cases degrade performance since more options 
                are available in the tables, requiring more bits to encode strings. The default value is false, 
                meaning that buffers, string tables, etc., are cleared between each stanza.</xs:documentation>
            </xs:annotation>
        </xs:attribute>
    </xs:attributeGroup>
 
    <xs:simpleType name='MD5Hash'>
        <xs:restriction base='xs:string'>
            <xs:pattern value='^[0-9a-f]{32}$'/>
        </xs:restriction>
    </xs:simpleType>
 
    <xs:simpleType name='Alignment'>
        <xs:restriction base='xs:string'>
            <xs:enumeration value='bit-packed'>
                <xs:annotation>
                    <xs:documentation>The alignment option value bit-packed indicates that the event codes and associated 
                    content are packed in bits without any padding in-between.</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value='byte-alignment'>
                <xs:annotation>
                    <xs:documentation>The alignment option value byte-alignment indicates that the event codes and 
                    associated content are aligned on byte boundaries. While byte-alignment generally results in EXI 
                    streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a 
                    help in some use cases that involve frequent copying of large arrays of scalar data directly out 
                    of the stream. It can also make it possible to work with data in-place and can make it easier to 
                    debug encoded data by allowing items on aligned boundaries to be easily located in the stream.</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
            <xs:enumeration value='pre-compression'>
                <xs:annotation>
                    <xs:documentation>The alignment option value pre-compression indicates that all steps involved 
                    in compression (see section 9. EXI Compression) are to be done with the exception of the final 
                    step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a 
                    duplicate compression step when compression capability is built into the transport protocol. In 
                    this case, pre-compression just prepares the stream for later compression.</xs:documentation>
                </xs:annotation>
            </xs:enumeration>
        </xs:restriction>
    </xs:simpleType>
 
	<xs:element name='uploadSchema'>
		<xs:complexType>
			<xs:simpleContent>
				<xs:extension base='xs:base64Binary'>
					<xs:attribute name='contentType' type='ContentType' use='optional' default='Text'/>
					<xs:attribute name='bytes' type='xs:positiveInteger' use='optional'/>
					<xs:attribute name='md5Hash' type='MD5Hash' use='optional'/>
				</xs:extension>
			</xs:simpleContent>
		</xs:complexType>
	</xs:element>
 
	<xs:simpleType name='ContentType'>
		<xs:restriction base='xs:string'>
			<xs:enumeration value='Text'/>
			<xs:enumeration value='ExiBody'/>
			<xs:enumeration value='ExiDocument'/>
		</xs:restriction>
	</xs:simpleType>
 
    <xs:element name='downloadSchema' type='DownloadSchema'/>
    <xs:element name='downloadSchemaResponse' type='DownloadSchemaResponse'/>

    <xs:complexType name='DownloadSchema'>
        <xs:attribute name='url' type='xs:string' use='required'/>
    </xs:complexType>
  
    <xs:complexType name='DownloadSchemaResponse'>
        <xs:complexContent>
            <xs:extension base='DownloadSchema'>
                <xs:choice minOccurs='0' maxOccurs='1'>
                    <xs:element name='httpError'>
                        <xs:complexType>
                            <xs:attribute name='code' type='xs:positiveInteger' use='required'/>
                            <xs:attribute name='message' type='xs:string' use='required'/>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name='invalidUrl'>
                        <xs:complexType>
                            <xs:attribute name='message' type='xs:string' use='required'/>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name='timeout'>
                        <xs:complexType>
                            <xs:attribute name='message' type='xs:string' use='required'/>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name='invalidContentType'>
                        <xs:complexType>
                            <xs:attribute name='contentTypeReturned' type='xs:string' use='required'/>
                        </xs:complexType>
                    </xs:element>
                    <xs:element name='error'>
                        <xs:complexType>
                            <xs:attribute name='message' type='xs:string' use='required'/>
                        </xs:complexType>
                    </xs:element>
                </xs:choice>
                <xs:attribute name='result' type='xs:boolean' use='required'/>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
 
</xs:schema>

        

8. Acknowledgements

Thanks to Joachim Lindborg, Yusuke Doi, Takuki Kamiya, Tina Beckman, Karin Forsell, Jeff Freund and Rumen Kyusakov for all valuable feedback.


Appendices


Appendix A: Document Information

Series: XEP
Number: 0322
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.1
Last Updated: 2013-04-16
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0001, XEP-0138
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
Source Control: HTML
This document in other formats: XML  PDF


Appendix B: Author Information

Peter Waher

Email: peter.waher@clayster.com
JabberID: peter.waher@jabber.org
URI: http://se.linkedin.com/pub/peter-waher/1a/71b/a29/


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2013 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) 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.


Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.


Appendix F: Requirements Conformance

The following requirements 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".


Appendix G: Notes

1. Efficient XML Interchange (EXI) Format <http://www.w3.org/TR/exi/>.

2. XEP-0138: Stream Compression <http://xmpp.org/extensions/xep-0138.html>.

3. 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/>.


Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.1 (2013-04-16)

Initial published version approved by the XMPP Council.

(psa)

Version 0.0.4 (2013-03-19)

Added support for uploading EXI-compressed schema files.

(pwa)

Version 0.0.3 (2013-03-15)

Added definition: EXI body.

Added note regarding preserverance of namespace prefixes.

Corrected the language.

(pwa)

Version 0.0.2 (2013-03-13)

Added support for session-wide buffers and string tables.

(pwa)

Version 0.0.1 (2013-03-12)

First draft.

(pwa)

END