Skip to content

# Roster versioning

Roster versioning as implemented currently by ejabberd is a simplified approach to roster versioning.

This is an all-or-nothing approach that does not support the granular diff as explained in RFC-6121.

Our implementation conforms to version 0.6 of XEP-0237, sending the full roster in case of change or empty result if the roster did not change.

As a result, as a client developer, when implementing support for roster versioning, you should expect both the traditional form for returning the roster, with version (iq result) and the incremental roster changes (iq set).

### Example

As a summary, here is how you should expect it to work.

First, you can check that the feature is advertised in the `stream:features` as `urn:xmpp:features:rosterver`:

    <stream:features>
     <bind xmlns="urn:ietf:params:xml:ns:xmpp-bind"/>
     <session xmlns="urn:ietf:params:xml:ns:xmpp-session">
      <optional/>
      </session>
      <c xmlns="http://jabber.org/protocol/caps" node="http://www.process-one.net/en/ejabberd/" ver="/lmQr0llUEtX/pIt+6BDAbnIT/U=" hash="sha-1"/>
      <sm xmlns="urn:xmpp:sm:2"/>
      <sm xmlns="urn:xmpp:sm:3"/>
      <ver xmlns="urn:xmpp:features:rosterver"/>
    </stream:features>

You can then bootstrap the use of roster versioning using empty `ver` attribute when sending your roster `get` iq:

    <iq id='roster1' to='myuser@domain.com' type='get'>
     <query xmlns='jabber:iq:roster' ver=''/>
    </iq>

In return, you get a full roster with the current version:

    <iq from="myuser@domain.com" type="result" xml:lang="en" to="myuser@domain.com/resource" id="roster1">
     <query xmlns="jabber:iq:roster" ver="81cb523a7b77c7011552be85a3dde55189297590">
      <item subscription="both" jid="contact@domain.com">
       <group>Test</group>
      </item>
      ...
     </query>
    </iq>

The client can store this version to send subsequent roster queries.

If client send a roster query with reference version it received get an empty iq result meaning the roster did not change:

    <iq id="roster2" to="myuser@domain.com" type="get">
     <query xmlns='jabber:iq:roster' ver='81cb523a7b77c7011552be85a3dde55189297590'/>
    </iq>

    <iq from="myuser@domain.com" type="result" xml:lang="en" to="myuser@domain.com/resource" id="roster2"/>

If client send roster query with any other reference version, it will receive the full roster again in the roster iq result.