XEP-xxxx: IO-Object Forms

This document describes a methode for publishing and transporting improved Web Services over XMPP.


WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document must not be referred to as an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://www.xmpp.org/extensions/> and announced on the <standards@xmpp.org> mailing list.


Document Information

Series: XEP
Number: xxxx
Publisher: XMPP Standards Foundation
Status: ProtoXEP
Type: Standards Track
Version: 0.0.1
Last Updated: 2007-02-26
Approving Body: XMPP Council
Dependencies: XMPP Core, XEP-0001, XEP-0030, XEP-0050
Supersedes: None
Superseded By: None
Short Name: Not yet assigned

Author Information

Johannes Wagener

Email: johannes.wagener@med.uni-muenchen.de
JabberID: edrin@jabber.org

Andreas Heusler

Email: aheusler@in.tum.de
JabberID: krach@jabber.org

Egon Willighagen

Email: egonw@users.sf.net
JabberID: egonw@jabber.org

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
    1.1. About the intention to define this XEP
    1.2. Limitations of existing XEPs
    1.3. The IO-Object Forms
2. Requirements
3. Glossary
4. Use Cases
5. Error Codes
6. Implementation Notes
7. Internationalization Considerations
8. Security Considerations
9. IANA Considerations
10. XMPP Registrar Considerations
11. XML Schema
12. Acknowledgements
Notes
Revision History


1. Introduction

As defined by the World Wide Web Consortium (W3C) [1], a Web Service is a software system designed to support interoperable Machine to Machine interaction over a network. In many cases Web Services are just application programming interfaces (API) that can be accessed over networks and execute a function on a remote system. This XEP is based on Ad-Hoc Commands [2] to accomplish remote code execution over XMPP. In addition to that it provides a new namespace to envelope Web Services data elements (the remote functions parameters and results) called IO-OBJECT FORMS that is required due to the limitations of Data Forms [3].

In addition to that it provides use cases that show:

  1. For your convenience, how to discover support by exploiting Service Discovery [4].
  2. For your convenience, how to retrieve the command list as defined in Ad-Hoc-Commands.
  3. How to retrieve the IO-OBJECT FORMS.
  4. How to execute a remote command in a synchronous way.
  5. How to execute a remote command in an asynchronous way.

1.1 About the intention to define this XEP

Many individuals consider SOAP or XML-RPC to be a synonym for Web Services. However, Web service definition encompasses many different systems. For certain reasons it makes sense to tunnel remote functions over an interconnected network based on XMPP. First, XMPP is a well established and widely accepted protocol. Second, XMPP provides unique static entity identifiers that are independent of potentially dynamic IP addresses. Third, XMPP and its extensions already define plenty of techniques to perform complex tasks that can combine with Web Services, for example SOCKS5 Bytestreams [5].

Technical implementations of Web Services have special requirements depending on the task that has to be performed. In certain fields, for example in bioinformatics, the implementation must support:

1.2 Limitations of existing XEPs

Several XEPs exist that provide mechanisms to execute a function on a remote system. For this count Jabber-RPC [6], SOAP over XMPP [7] and Ad-Hoc Commands. While each of these XEPs target some of the requirements listed above, none can achieve all of them.

Ad-Hoc Commands was primarily designed for human-oriented commands by making use of Data Forms, an XEP that has limited capability to envelope complex data structures, to render a graphical user interface (GUI) without the intention to replace Jabber-RPC or SOAP over XMPP;.

However, for certain machine to machine processes Jabber-RPC and SOAP over XMPP lack functionality.

Because of the limited complexity of XML-RPCs data types the Jabber-RPC is not suitable for complex functionality, similar to the limitations of Data Forms.

While SOAP over XMPP supports complex functionality it lacks an obvious mechanism for asynchronous usage. In addition to that the SOAP standard itself is very complicate, basically overqualified as it was defined as a HTTP and SMTP based standard. In addition to that its usage depends on WSDL [8], a standard to define SOAP based Web Services functions and data structures (function-parameters and results). Taken together this means that implementing SOAP based Web Services over XMPP would also require the distribution of files over XMPP or WSDL with another protocol which leads to an overload of complexity, and still there would be no obvious mechanism for asynchronous usage.

1.3 The IO-Object Forms

Ad-Hoc Commands defines a way for asynchronous usage but lacks a namespace for complex machine to machine commands. In consequence this XEP defines a namespace called IO-OBJECT FORMS (Input-Output-Object Form) for machine to machine communication and provides use cases. IO-OBJECT FORMS does not compete against the application of Data Forms as it targets to be used in cases where no direct graphical user interface based human interaction is required. In fact a Web Service could even export both forms to provide an API for developers/researchers and a GUI for users in parallel.

2. Requirements

This document addresses the following requirements:

  1. Extend Ad-Hoc Commands with discoverable machine to machine functionality.
  2. Provide use cases for this machine to machine functionality.
  3. Suggest rules for implementation of machine to machine commands based on XMPP.

3. Glossary

A machine to machine command means the execution of a remote function while both entities do not have to be human.

4. Use Cases

4.1 Discovering Support

To determine if an entity supports x-commands, the requester uses Service Discovery. The requester makes an "#info" query to the responder. If supported, the responder includes a <feature/> with the "var" of "http://jabber.org/protocol/commands".

4.1.1 Disco request for information

Example 1. Disco request for information

<iq type='get'
    from='user@university.org'
    to='service.university.org'
    id='iq_123'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
    

4.1.2 Disco result for information

Example 2. Disco result for information

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_123'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://jabber.org/protocol/commands'/>
    ...
  </query>
</iq>

4.2 Retrieving the Command List

To find what commands an entity provides, the requester uses Service Discovery. Each command is a node of the responder, under the fixed node "http://jabber.org/protocol/commands" (for which the service discovery identity category is "automation" and type is "command-list"). Use of a fixed node for all commands of an entity allows for immediate retrieval of commands.

Each command is a disco item. The node attribute of <item/> identifies the command, and the name attribute is the label for the command.

The requester retrieves the list of commands by querying for the responder's items for the node "http://jabber.org/protocol/commands":

4.2.1 Disco request for command items

Example 3. Disco request for command items

<iq type='get'
    from='user@university.org'
    to='service.university.org'
    id='iq_124'>
  <query xmlns='http://jabber.org/protocol/disco#items'
      node='http://jabber.org/protocol/commands'/>
</iq>

4.2.2 Disco result for command items

Example 4. Disco result for command items

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_124'>
  <query xmlns='http://jabber.org/protocol/disco#items'
      node='http://jabber.org/protocol/commands'>
    <item jid='service.university.org'
        node='get_proteinsequence'
        name='Request a protein sequence by identifier'/>
    <item jid='service.university.org'
        node='get_dnasequence'
      name='Request a DNA sequence by identifier'/>
    <item jid='service.university.org'
        node='get_threedimensionalcoordinates'
      name='Returns 3D atomic coordinates for the input structure'/>
  </query>
</iq>

The requester can query for disco information on the command node to find out if it supports IO-Object Forms' based commands.

4.2.3 Disco request for command information

Example 5. Disco request for command information

<iq type='get'
    from='user@university.org'
    to='service.university.org'
    id='iq_125'>
  <query xmlns='http://jabber.org/protocol/disco#info'
      node='get_proteinsequence'/>
</iq>

4.2.4 Disco result for command information

Example 6. Disco result for command information

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_125'>
  <query xmlns='http://jabber.org/protocol/disco#info'
      node='get_proteinsequence'>
    <feature var='http://jabber.org/protocol/commands'/>
    <feature var='jabber:x:data'/>
    <feature var='http://xmpp.org/protocol/io-object-form'/>
  </query>
</iq>

To indicate support for IO-OBJECT FORMS it MUST include <feature var='http://xmpp.org/protocol/io-object-form'/>. Of course the node can still provide <feature var='jabber:x:data'/>.

4.3 Retrieving the IO-Object Form

A machine can request details and instructions (machine to machine form) about the remote functionality using 'get' with Ad-Hoc Commands. In addition to that the responder's result will inform the requester about support for asynchronous execution.

4.3.1 Command request - sample 1

Example 7. Command request - sample 1

<iq type='get'
    from='user@university.org'
    to='service.university.org'
    id='iq_126a'>
  <command xmlns='http://jabber.org/protocol/commands'
      node='get_proteinsequence'/>
</iq>

4.3.2 Command result - sample 1

Example 8. Command result - sample 1

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_126a'>
  <command xmlns='http://jabber.org/protocol/commands'
      node='get_proteinsequence'>
    <actions execute='complete'>
      <complete/>
      <next/>
    </actions>
    <x xmlns='http://xmpp.org/protocol/io-object-form' type='form'>
      <desc>
        This Ad-Hoc Command returns the protein sequence.
      </desc>
      <in>
        <xs:complexType>
          <xs:element name='proteinname'
              type='xs:string'
              use='required'/>
        </xs:complexType>
      </in>
      <out>
        <xs:complexType>
          <xs:element name='proteinsequence'
              type='xs:string'
              use='required'/>
        </xs:complexType>
      </out>
    </x>
  </command>
</iq>

The 'actions' element indicates an asynchronous (element 'next') or synchronous (element 'complete') function or both. The namespace 'http://xmpp.org/protocol/io-object-form' in combination with 'type' "form" defines the function with description (<desc/>) and XML schemata for input (<in/>) and output (<out/>).

4.3.3 Command request - sample 2

Example 9. Command request - sample 2

<iq type='get'
    from='user@university.org'
    to='service.university.org'
    id='iq_126b'>
  <command xmlns='http://jabber.org/protocol/commands'
      node='get_threedimensionalcoordinates'/>
</iq>

4.3.4 Command result - sample 2

Example 10. Command result - sample 2


<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_126b'>
  <command xmlns='http://jabber.org/protocol/commands'
      node='get_threedimensionalcoordinates'>
    <actions execute='complete'>
      <complete/>
      <next/>
    </actions>
    <x xmlns='http://xmpp.org/protocol/io-object-form' type='form'>
      <desc>
        This Ad-Hoc command Returns 3D atomic coordinates for the
        input structure.
      </desc>
      <in>
        <xs:complexType>
          <xs:any namespace='http://www.xml-cml.org/schema'
              minOccur='1' maxOccur='1'/>
        </xs:complexType>
      </in>
      <out>
        <xs:complexType>
          <xs:any namespace='http://www.xml-cml.org/schema'
              minOccur='1' maxOccur='1'/>
        </xs:complexType>
      </out>
    </x>
  </command>
</iq>

This service requires the content of the form to be Chemical Markup Language [9] by requiring input with the namespace 'http://www.xml-cml.org/schema'. Additionally, it also defines the returned output to be Chemical Markup Language.

4.4 Executing a Synchronous Command

The 'actions' child element 'complete' indicates a synchronous function that will return the result directly after completion.

4.4.1 Execute Command request

Example 11. Execute Command request

<iq type='set'
    from='user@university.org'
    to='service.university.org'
    id='iq_127'>
  <command xmlns='http://jabber.org/protocol/commands'
      node='get_proteinsequence'
      action='complete'/>
    <x xmlns='http://xmpp.org/protocol/io-object-form' type='submit'>
      <in>
        <proteinname>
          CAB08284
        </proteinname>
      </in>
    </x>
  </command>
</iq>

4.4.2 Execute command result

Example 12. Execute command result

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_127'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000001'
      node='get_proteinsequence'
      status='completed'>
    <x xmlns='http://xmpp.org/protocol/io-object-form' type='result'>
      <out>
        <proteinsequence>
          mrkhpqsatk hlfvsggvas slgkgltass lgqlltargl hvtmqkldpy lnvdpgtmnp
          fqhgevfvte dgaetdldvg hyerfldrdl sgsanvttgq vystviaker rgeylgdtvq
          viphitdeik qrimamaqpd ggdnrpdvvi teiggtvgdi esqpfleaar qvrhdlgren
          vfflhvslvp hlapsgelkt kptqhsvaal rsigitpdal ilrcdrdvpe slknkialmc
          dvdidgvist pdapsiydip kvlhreelda fvvrrlnlpf rdvdwtewdd llrrvhephg
          tvrialvgky vdfsdaylsv sealhaggfk hyakvevvwv asddcetatg aaavladvhg
          vlipggfgir giegkigair yararglpvl glclglqciv ieatrsvglv qansaefepa
          tpdpvistma dqkeivagea dfggtmrlga ypavlqpasi vaqaygttqv serhrhryev
          nnayrdwiae sglrisgtsp dgylvefvey panmhpfvvg tqahpelksr ptrphplfva
          fvgaaidyks aellpveipa vpeisehlpn ssnqhrdgve rsfpapaarg
        </proteinsequence>
      </out>
    </x>
  </command>
</iq>

4.5 Executing an Asynchronous Command

The 'actions' child element 'next' indicates an asynchronous function that will return the result upon request. This is useful in cases where the responder executes a calculation or time expensive task. The requester can check for the current status (executing/completed) whenever he wants. In addition to that the responder will inform the requester about completion with a message.

4.5.1 Execute command request (stage 1)

Example 13. Execute command request (stage 1)

<iq type='set'
    from='user@university.org'
    to='service.university.org'
    id='iq_128'>
  <command xmlns='http://jabber.org/protocol/commands'
      node='get_proteinsequence'
      action='next'>
    <x xmlns='http://xmpp.org/protocol/io-object-form' type='submit'>
      <in>
        <proteinname>
          CAB08284
        </proteinname>
      </in>
    </x>
  </command>
</iq>

4.5.2 Execute command result (stage 1)

Example 14. Execute command result (stage 1)

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_128'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000010'
      node='get_proteinsequence'
      status='executing'>
    <note type='info'>Service has been started. You may stay up to
        date using the next-action.</note>
    <actions execute='next'>
      <next/>
    </actions>
  </command>
</iq>

The requester MUST now store the 'sessionid' to check the status and finally request the result or to cancel the execution.

4.5.3 Check command status request

The requester can now check the status of the execution using the 'action' attribute "next".

Example 15. Check command status request

<iq type='set'
    from='user@university.org'
    to='service.university.org'
    id='iq_129'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000010'      
      node='get_proteinsequence'
      action='next'/>
</iq>

4.5.4 Check command status result (alternative 1)

The job is not finished yet, the responder answers with 'actions' child element 'next'.

Example 16. Check command status result (alternative 1)

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_129'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000010'
      node='get_proteinsequence'
      status='executing'>
    <note type='info'>Service has been started. You may stay up to
        date using the next-action.</note>
    <actions execute='next'>
      <next/>
    </actions>
  </command>
</iq>

4.5.5 Check command status result (alternative 2)

The job has finished. The responder answers with 'actions' child element 'next' but also 'complete'.

Example 17. Check command status result (alternative 2)

<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_129'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000010'
      node='get_proteinsequence'
      status='executing'>
    <note type='info'>Service has completed. You may request the result
        using the complete-action.</note>
    <actions execute='complete'>
      <next/>
      <complete/>
    </actions>
  </command>
</iq>

4.5.6 Announcing completion (via <message/>)

An asynchronous service MUST send a message on completion to inform the requester about completion.

Example 18. Announcing completion (via <message/>)

<message from='service.university.org'
    to='user@university.org'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000010'
      node='get_proteinsequence'
      status='executing'>
    <actions execute='complete'>
      <complete/>
      <next/>
    </actions>
  </command>
</message>

In fact it could happen that the request misses the message or is not reachable. In these cases the requester is responsible to stay up to date by requesting the status as described before.

4.5.7 Execute command request (stage 2)

The requester will finally request the result with the 'action' attribute "complete".

Example 19. Execute command request (stage 2)


<iq type='set'
    from='user@university.org'
    to='service.university.org'
    id='iq_129'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000001'
      node='get_proteinsequence'
      action='complete'/>
</iq>

4.5.8 Execute command result (stage 2)

Example 20. Execute command result (stage 2)


<iq type='result'
    from='service.university.org'
    to='user@university.org'
    id='iq_129'>
  <command xmlns='http://jabber.org/protocol/commands'
      sessionid='RPC-SESSION-0000001'
      node='get_proteinsequence'
      status='completed'>
    <x xmlns='http://xmpp.org/protocol/io-object-form' type='result'>
      <out>
        <proteinsequence>
          mrkhpqsatk hlfvsggvas slgkgltass lgqlltargl hvtmqkldpy lnvdpgtmnp
          fqhgevfvte dgaetdldvg hyerfldrdl sgsanvttgq vystviaker rgeylgdtvq
          viphitdeik qrimamaqpd ggdnrpdvvi teiggtvgdi esqpfleaar qvrhdlgren
          vfflhvslvp hlapsgelkt kptqhsvaal rsigitpdal ilrcdrdvpe slknkialmc
          dvdidgvist pdapsiydip kvlhreelda fvvrrlnlpf rdvdwtewdd llrrvhephg
          tvrialvgky vdfsdaylsv sealhaggfk hyakvevvwv asddcetatg aaavladvhg
          vlipggfgir giegkigair yararglpvl glclglqciv ieatrsvglv qansaefepa
          tpdpvistma dqkeivagea dfggtmrlga ypavlqpasi vaqaygttqv serhrhryev
          nnayrdwiae sglrisgtsp dgylvefvey panmhpfvvg tqahpelksr ptrphplfva
          fvgaaidyks aellpveipa vpeisehlpn ssnqhrdgve rsfpapaarg
        </proteinsequence>
      </out>
    </x>
  </command>
</iq>

5. Error Codes

Error codes within a command session (in the optional element 'note') are inherited from Ad-Hoc Commands.

6. Implementation Notes

Depending on the functionality of the command the service (responder) should expose the command in a synchronous or asynchronous way.

Formalising machine to machine commands using the namespace defined herein, making such commands detectable and usable on-the-fly without the prerequisite for the requester to know the exact interface on the service site and the support for asynchronous as well as synchronous execution contributes to the usability of XMPP for complex grid-computing projects.

In example an IDE could support the development of such projects by generating code interfaces (client stubs) to machine to machine capable XMPP services by discovering and requesting all required information on-the-fly.

7. Internationalization Considerations

Internationalization of messages sent by the server is covered by setting the @xml:lang attribute of the <iq> element. Services should reply in the same language in which the client asked the question. That is, if the client specifies a locale using the @xml:lang attribute on the <iq> element, then the server should reply in the same locale, and localize messages given in <desc>, <node>@info and <query><item>@name.

8. Security Considerations

None.

9. IANA Considerations

None.

10. XMPP Registrar Considerations

None.

11. XML Schema

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

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='http://xmpp.org/protocol/io-object-form'
    xmlns='http://xmpp.org/protocol/io-object-form'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0???: http://www.xmpp.org/extensions/xep-0???.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='x'>
    <xs:complexType>
      <xs:element name='desc' minOccurs='0' maxOccurs='1'
                  type='xs:string'/>
      <xs:element name='in' minOccurs='0' maxOccurs='1'/>
      <xs:element name='out' minOccurs='0' maxOccurs='1'/>
      <xs:attribute name='type' use='required'>
        <xs:simpleType>
          <xs:restriction base='xs:NCName'>
            <xs:enumeration value='cancel'/>
            <xs:enumeration value='form'/>
            <xs:enumeration value='result'/>
            <xs:enumeration value='submit'/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
    </xs:complexType>
  </xs:element>

  <xs:element name='in'>
    <xs:choice>
      <!-- for x@type='form' : -->
      <xs:any namespace='http://www.w3.org/2001/XMLSchema'
              minOccurrence='1' maxOccurence='1'/>
      <!-- for x@type='submit,results,etc' : -->
      <xs:any namespace='##other' processContents='strict'/>
    </xs:choice>
  </xs:element>

  <xs:element name='out'>
    <xs:choice>
      <!-- for x@type='form' : -->
      <xs:any namespace='http://www.w3.org/2001/XMLSchema'
              minOccurrence='1' maxOccurence='1'/>
      <!-- for x@type='submit,results,etc' : -->
      <xs:any namespace='##other' processContents='strict'/>
    </xs:choice>
  </xs:element>

</xs:schema>
    

12. Acknowledgements

The Bioclipse Project


Notes

1. The World Wide Web Consortium defines data formats and markup languages (such as HTML and XML) for use over the Internet. For further information, see <http://www.w3.org/>.

2. XEP-0050: Ad-Hoc Commands <http://www.xmpp.org/extensions/xep-0050.html>.

3. XEP-0004: Data Forms <http://www.xmpp.org/extensions/xep-0004.html>.

4. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.

5. XEP-0065: SOCKS5 Bytestreams <http://www.xmpp.org/extensions/xep-0065.html>.

6. XEP-0009: Jabber-RPC <http://www.xmpp.org/extensions/xep-0009.html>.

7. XEP-0072: SOAP over XMPP <http://www.xmpp.org/extensions/xep-0072.html>.

8. The W3C-description for WSDL can be found at <http://www.w3.org/TR/wsdl>.

9. The Chemical Markup Language: <http://www.xml-cml.org/>.


Revision History

Version 0.0.1 (2007-02-26)

Initial Version.

(jw/ah)

END