XEP-0413: Order-By

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

Publish-Subscribe (XEP-0060) [1] §6.5.7 allows to retrieve the "most recent items" and Message Archive Management (XEP-0313) [2] state in §3.1 that archives are ordered in "chrnological order". While this order is straighforward in general use cases, it is sometimes desirable to use a different order, for instance while using Microblogging Over XMPP (XEP-0277) [3]: a spell mistake correction should not bring an old blog post to the top of retrieved items.

This specification allows to explicitly change business logic to retrieve the items in a different order, in a similar way as the "ORDER BY" clause in SQL.

2. Requirements

• an entity should be able to retrieve items by date of creation or by date of last modification (see below for definitions)
• the specification should be extensible to allow new ordering
• in case of conflict, a 2nd, 3rd, etc. level of ordering should be possible

3. Glossary

In XEP-0060, there is no such thing as "updated item". This XEP changes the business logic as follow:

• Date of creation — date when the item has been published ONLY if the item has a new id (i.e. an id which was not already present in the node at the time of publication). If an item re-use an existing id, it overwrites the original item and the date of creation stay the date of creation of the original item
• Date of modification — date when the item has been overwritten by a new item of the same id. If the item has never been overwritten, it is equal to the date of creation defined above.

4. Use Cases

<iq type='get'
    from='juliet@capulet.lit/balcony'
    to='pubsub.shakespeare.lit'
    id=''>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='plays' max_items='3'/>
    <order xmlns='urn:xmpp:order-by:0' by='creation'/>
  </pubsub>
</iq>
  

<iq type='result'
    from='pubsub.shakespeare.lit'
    to='juliet@capulet.lit/balcony'
    id=''>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='plays'>
      <item id='153214214'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Henry VIII</title>
        </entry>
      </item>
      <item id='623423544'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Tempest</title>
        </entry>
      </item>
      <item id='452432423'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Wintter's Tale</title>
        </entry>
      </item>
    </items>
  </pubsub>
</iq>

<iq type='set'
    from='juliet@capulet.lit/balcony'
    to='pubsub.shakespeare.lit'
    id='orderby2'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='plays'>
      <item id='452432423'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Winter's Tale</title>
        </entry>
      </item>
    </publish>
  </pubsub>
</iq>

<iq type='get'
    from='juliet@capulet.lit/balcony'
    to='pubsub.shakespeare.lit'
    id='orderby3'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='plays' max_items='3'/>
    <order xmlns='urn:xmpp:order-by:0' by='modification'/>
  </pubsub>
</iq>
  

<iq type='result'
    from='pubsub.shakespeare.lit'
    to='juliet@capulet.lit/balcony'
    id='orderby3'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='plays'>
      <item id='452432423'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Winter's Tale</title>
        </entry>
      </item>
      <item id='153214214'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Henry VIII</title>
        </entry>
      </item>
      <item id='623423544'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Tempest</title>
        </entry>
      </item>
    </items>
  </pubsub>
</iq>

<iq to='pubsub.shakespeare.lit' type='set' id='orderby4'>
  <query xmlns='urn:xmpp:mam:2' queryid='123' node='plays'>
    <order xmlns='urn:xmpp:order-by:0' by='creation'/>
  </query>
</iq>

5. Discovering Support

If a server supports the "order by" protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:order-by:0" (see Protocol Namespaces regarding issuance of one or more permanent namespaces) in response to a Service Discovery (XEP-0030) [5] information request:

Example 7. Service Discovery information request

<iq from='example.org'
    id='disco1'
    to='example.com'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

Example 8. Service Discovery information response

<iq from='example.com'
    id='disco1'
    to='example.org'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:order-by:0'/>
    ...
  </query>
</iq>

6. Business Rules

Several ordering elements may be used, this allow to solve next levels of ordering in case of conflicts. In this case, the first ordering (i.e. the top most <order> element) is the main one, the the second <order> element is used in case of conflict, then the next one if a new conflict happen and so on.

In case of conflict, if no new <order> element is specified, the item order is not guarented and is up to the implementation

7. Implementation Notes

For implementations based on SQL databases, the "ORDER BY" clause can be used to easily implement this specification. Other kind of databases should have similar mechanisms

8. Security Considerations

This document introduces no additional security considerations above and beyond those defined in the documents on which it depends.

9. IANA Considerations

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

10. XMPP Registrar Considerations

11. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:order-by:0'
    xmlns='urn:xmpp:order-by:0'
    elementFormDefault='qualified'>

  <xs:element name='order' maxOccurs='unbounded'>
      <xs:complexType>
          <xs:attribute name='by' type='xs:string' use='required'/>
      </xs:complexType>
  </xs:element>

</xs:schema>

Appendices

Appendix A: Document Information

Series: XEP
Number: 0413
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.1.0
Last Updated: 2019-02-04
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0060, XEP-0313
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
Source Control: HTML
This document in other formats: XML  PDF

Appendix B: Author Information

Appendix C: Legal Notices

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

Appendix H: Revision History

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

END