Qworum specification, version 1.2

Introduction
Service composition

Multi-phase service calls
Special case: the World Wide Web
Special case: RPC
The user agent as mediator for service calls

Messages

Message format
Message evaluation by the user agent
The http://www.qworum.com/ XML namespace
The application/x-qworum+xml media type
The .qrm file extension

Statements

The call statement
The data statement
The fault statement
The goto statement
The nil statement
The return statement
The sequence statement
The transient statement
The try statement
The variable statement

Appendices

References
Handling non-conforming messages
Changes between version 1.1 and version 1.2
Revision history

1. Introduction

The World Wide Web is a system of interlinked hypertext documents accessed via the Internet. Although its initial purpose was to provide an infrastructure for information, the World Wide Web is increasingly being used for web applications, which arguably have additional infrastructure needs.

In this context, Qworum defines a component standard for web applications. Web developers can use Qworum for dividing a web application into several reusable components, which are also called Qworum services. The components that make up a web application do not need to reside all on one single server. With Qworum, the barriers that exist between websites are largely overcome, so that websites can provide services to each other much more easily. In particular, websites can provide interactive services that seamlessly integrate into other websites.

For service providers, the advantage of using Qworum is that services can be interactive as a regular website, or non-interactive as a remote procedure call. In fact, the same service may be interactive during one call, and non-interactive during the next one. In other words, Qworum unifies the World Wide Web and remote procedure call concepts.

Qworum makes use of a specific web message format, which offers functionality that is orthogonal to that of existing web formats such as HTML. As a result, the Qworum specification is expected to evolve independently from those standards.

The present specification provides relevant information for the following groups:

Developers of Qworum services, and
Developers of user agents.

2. Service composition

Qworum is based on the concept of multi-phase services. The service composition mechanism used by Qworum is directly derived from this concept, and explains the design choices made by Qworum. This and related concepts are described below.

The term phase refers to the following three consecutive steps:

a user agent sends a request to a server,
the server performs an operation based on the request and produces a response,
the user agent receives the response from the server.

A phase

According to this definition, conventional remote procedure calls (based on XML-RPC for instance) always consist of a single phase.

The term service refers to a software functionality available on a computer, and used by programs on other computers through network connections. In the context of Qworum, a service is available at a URL that has an http or https scheme, and services are identified by their URL.

2.1. Multi-phase service calls

The term multi-phase service refers to a service whose calls consist of one or more phases.

A multi-phase service call may span several servers, and terminates when the user agent receives a response containing a result message.

In order to continue the current call, a phase may return a response that does not contain a result message. In this case, the user agent will try to use the message for initiating the next phase of the current call. When the HTTP protocol is used, HTTP redirections and interaction messages such as HTML pages allow such call continuations. Another way of performing call continuations is through the use of composition messages.

A multi-phase service call consisting of three phases, using the HTTP protocol

2.2. Special case: the World Wide Web

The multi-phase service call concept is more general than the World Wide Web paradigm.

Indeed, a web browsing session inside a browser tab (or window) is equivalent to a multi-phase service call which never returns a result, and which never calls other services by using the proposed composition mechanism.

2.3. Special case: RPC

The multi-phase service call concept is also more general than the concept of remote procedure call: a multi-phase service call consisting of a single phase is equivalent to a conventional remote procedure call.

2.4. The user agent as mediator for service calls

According to the proposed composition mechanism, a service calls another service as follows:

The calling service sends a composition message to the user agent.
Based on the instructions contained in this message, the user agent then performs the service call, between two consecutive phases of the calling service.
The service call terminates when one of its phases sends a result message to the user agent.
The user agent then sends the received result to the calling service, at a URL specified in the composition message previously received.

Service composition: a service on a first server calls a service on a second server

Qworum does not impose any restrictions on the number of nested calls: a service may call another service, which calls another service, which calls yet another service, etc. A service may also make recursive calls to itself.

3. Messages

3.1. Message format

Qworum defines an XML [6] message format that supports the basic service composition pattern described in the previous section.

Here is a result message that might be returned by an e-mail lookup service:

<email>john.smith@email.com</email>

And here is a composition message used for calling the e-mail lookup service (goto describes the next phase of the current call, and call describes the service call to be performed by the user agent on behalf of the current call):

<qrm:goto href='receive_email_address' xmlns:qrm='http://www.qworum.com/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name> <-- call parameter -->
  </qrm:call>
</qrm:goto>

Qworum messages also enable more advanced usage patterns. Here is a message which is neither a pure result message, nor a composition message (this particular message might be described as a result message with parts provided by service calls):

<emails>
  <qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
    <name>John Smith</name>
  </qrm:call>
  <qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
    <name>Jack Smith</name>
  </qrm:call>
</emails>

3.2. Message evaluation by the user agent

Qworum messages are scripts, rather than human-centric documents. Each message consists of one statement, corresponding to the root XML element.

Upon receiving a message, the user agent starts evaluating it using the latest Qworum specification that it supports. Specifications are backward-compatible, meaning that if a message conforms to one version of the Qworum specification, then it conforms to all subsequent versions as well.

Most statements yield a result when evaluated. For example, the call statement:

<qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
  <name>John Smith</name>
</qrm:call>

yields a call result, which might be:

<email>john.smith@email.com</email>

And the data statement:

<emails>
  <qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
    <name>John Smith</name>
  </qrm:call>
  <qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
    <name>Jack Smith</name>
  </qrm:call>
</emails>

might yield:

<emails>
  <email>john.smith@email.com</email>
  <email>jack.smith@email.com</email>
</emails>

The following statements disrupt the flow of evaluation, and consequently do not yield a result:

goto
return
fault

Message evaluations are interrupted during a service call; they resume when the call terminates. A message evaluation ends when:

the next phase of the current call is initiated, or
the current call terminates.

The next phase of the current call is initiated when a goto statement is evaluated.

The current call terminates when:

the main statement (represented by the root XML element) yields a result, or
a return statement is evaluated, or
an uncaught fault is evaluated.

The user agent maintains an internal call stack for handling service calls. In the case of a web browser, each tab or window has a call stack associated with it.

Call stacks initially contain one frame, which represents the main service call. Call frames are used for storing variable values and messages whose evaluations were interrupted by service calls. The topmost call frame, corresponding to the current service call, does not contain any message.

3.3. The `http://www.qworum.com/` XML namespace

Qworum defines an XML vocabulary that is used in messages. All elements of this vocabulary belong to the namespace http://www.qworum.com/. Elements belonging to this namespace are also referred to as Qworum elements. Elements that do not belong to this namespace are also referred to as non-Qworum elements.

All statements are described by a Qworum element, except the data statement. Some Qworum elements, namely title and catch, do not describe a statement but are part of an enclosing statement.

3.4. The `application/x-qworum+xml` media type

The media type of Qworum messages is application/x-qworum+xml (media types are explained in the section 3.7 of the HTTP/1.1 specification [1]). It has a parameter named version.

User agents which support the present version of the Qworum specification must include the following in the Accept headers of the HTTP/HTTPS requests they generate:

application/x-qworum+xml;version=1.2

For example, a Qworum-enabled web browser might generate the following request header:

Accept: application/x-qworum+xml;version=1.2,text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5

If an HTTP/HTTPS response contains a Qworum message, then this media type must be used as the value of its Content-Type header. The version parameter should not be included in this header; the user agent will ignore it if present. For example, an HTTP/HTTPS response containing a Qworum message might include the following header:

Content-Type: application/x-qworum+xml

3.5. The `.qrm` file extension

The suggested extension for files containing a Qworum message is .qrm. For example, a file containing a message that calls a payment processing service might be named payment_processing_call.qrm.

4. Statements

4.1. The `call` statement

The call statement initiates a multi-phase service call. The evaluation of this statement is interrupted until the call returns a result. The evaluation then ends by yielding the call result.

call elements have an optional href attribute which indicates the URL of the first phase of the service to be called. The value of the href attribute may be an absolute HTTP or HTTPS URL [4], or a relative URL [5]. An absent href attribute is equivalent to an href attribute whose value is the URL of the message containing the call statement, and a relative URL is resolved using the message URL. For example, a request to http://www.ahost.com/path may return any one of the following messages; they will all initiate a call by sending a GET request to http://www.ahost.com/path:

<call xmlns='http://www.qworum.com/' />

<call href='path' xmlns='http://www.qworum.com/' />

<call href='http://www.ahost.com/path' xmlns='http://www.qworum.com/' />

call elements contain zero or one statement (the parameter statement). If the parameter statement is present then the call is initiated with a POST request whose body (which has the content type application/xml) contains the evaluation result of the parameter statement.

call elements contain zero, one or more title elements which briefly describe the call. An optional lang attribute indicates the human language that is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 [1] specification. title elements do not contain any elements.

For example, the following statement:

<qrm:call href='https://www.apaymentprocessingsite.com/process_payment' xmlns:qrm='http://www.qworum.com/'>
  <qrm:title>Calling the payment processing service ..</qrm:title>
  <payment>
    <description>1 x 1-year subscription for "A Business Magazine"</description>
    <total>98.95</total>
    <currency>USD</currency>
    <merchant>payments@anecommercesite.com</merchant>
  </payment>
</qrm:call>

sends a POST request to https://www.apaymentprocessingsite.com/process_payment, and the request body contains:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
</payment>

4.2. The data statement

Data statements are non-Qworum elements that may have other non-Qworum elements or statements as descendents. Their evaluation ends when the descendent statements have been evaluated. For example, the statement:

<emails>
  <qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
    <!-- this call is evaluated first -->
    <name>John Smith</name>
  </qrm:call>
  <qrm:call href='email_lookup' xmlns:qrm='http://www.qworum.com/'>
    <!-- this call is evaluated second -->
    <name>Jack Smith</name>
  </qrm:call>
</emails>

may yield:

<emails>
  <email>john.smith@email.com</email>
  <email>jack.smith@email.com</email>
</emails>

And the following statement remains unchanged after evaluation.

<name>John Smith</name>

4.3. The `fault` statement

The fault statement indicates an error condition that prevents a service call from proceeding normally. Faults may be caught and handled by try statements. Fault example:

<fault xmlns='http://www.qworum.com/' />

Faults are classified into types which narrow down the underlying cause of an error condition, so that each type of fault may be handled separately.

Fault types

Faults of type service are used explicitly by services during a call. Such faults may for example indicate an issue with the call parameter or server-side database access. It is the default fault type, so that the following statements are equivalent:

<fault type='service' xmlns='http://www.qworum.com/' />
<fault xmlns='http://www.qworum.com/' />

Services may use fault types that are not specified by the present specification. Such types must start with the * character. They are subtypes of the extension type, which is in turn a subtype of service. Example:

<fault type='* parameter is not a name' xmlns='http://www.qworum.com/' />

Faults of type message indicate that a message received by the user agent did not conform to the present specification.

Finally, faults of type user agent indicate that the user agent was unable to evaluate a statement, for example because of an internal error. This fault type has a subtype called authorization which applies to situations where a statement could not be evaluated because of authorization issues.

fault elements contain zero, one or more title elements which briefly describe the fault. An optional lang attribute indicates the human language that is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 [1] specification. title elements do not contain any elements. Example:

<fault xmlns='http://www.qworum.com/'>
  <title lang='de'>Unbekannte Aktie<title>
  <title lang='fr'>Code inconnu<title>
  <title>Unknown ticker symbol<title>
</fault>

4.4. The `goto` statement

The goto statement initiates the next phase of a multi-phase service call.

goto elements have an optional href attribute which indicates the URL of the next phase. The value of the href attribute may be an absolute HTTP or HTTPS URL [4], or a relative URL [5]. An absent href attribute is equivalent to an href attribute whose value is the URL of the message containing the goto statement, and a relative URL is resolved using the message URL. For example, a request to http://www.ahost.com/path may return any one of the following messages; they will all initiate the next phase of the current call by sending a GET request to http://www.ahost.com/path:

<goto xmlns='http://www.qworum.com/' />

<goto href='path' xmlns='http://www.qworum.com/' />

<goto href='http://www.ahost.com/path' xmlns='http://www.qworum.com/' />

goto elements contain zero or one statement (the parameter statement). If the parameter statement is present then the next phase is initiated with a POST request whose body (which has the content type application/xml) contains the evaluation result of the parameter statement.

goto elements contain zero, one or more title elements which briefly describe the next phase. An optional lang attribute indicates the human language that is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 [1] specification. title elements do not contain any elements.

For example, the following statement:

<qrm:goto href='http://www.anecommercesite.com/process_payment' xmlns:qrm='http://www.qworum.com/'>
  <qrm:title>Start processing the payment ..</qrm:title>
  <payment>
    <description>1 x 1-year subscription for "A Business Magazine"</description>
    <total>98.95</total>
    <currency>USD</currency>
    <merchant>payments@anecommercesite.com</merchant>
  </payment>
</qrm:goto>

sends a POST request to http://www.anecommercesite.com/process_payment, and the request body contains:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
</payment>

4.5. The `nil` statement

The nil statement represents data that does not carry any information. It remains unchanged after evaluation. Example:

<nil xmlns='http://www.qworum.com/' />

The nil element does not have any attributes, and does not contain any elements.

4.6. The `return` statement

The return statement terminates the current call by returning a result. It contains zero or one statement. For example, the statement:

<qrm:return xmlns:qrm='http://www.qworum.com/'>
  <email>john.smith@email.com</email>
</qrm:return>

returns the result:

<email>john.smith@email.com</email>

And the following statement returns nil:

<return xmlns='http://www.qworum.com/' />

The return element does not have any attributes.

4.7. The `sequence` statement

The sequence statement contains zero, one or more statements, each of which is evaluated in turn. The evaluation of this statement yields the result that is yielded by the last statement it contains. For example, the statement:

<qrm:sequence xmlns:qrm='http://www.qworum.com/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name>
  </qrm:call>
  <email>jack.smith@email.com</email>
</qrm:sequence>

yields (if the service call did not terminate with a fault):

<email>jack.smith@email.com</email>

And the following empty statement returns nil:

<sequence xmlns='http://www.qworum.com/' />

The sequence element does not have any attributes.

4.8. The `transient` statement

The transient statement is used for handling message variables, which exist only during the evaluation of a given message. The transient element has an attribute named name which identifies the message variable being handled.

When setting the value of a message variable, the transient element contains one statement which yields the value. The transient statement in turn yields that same value. For example, the statement:

<qrm:transient name='John&apos;s e-mail' xmlns:qrm='http://www.qworum.com/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name>
  </qrm:call>
</qrm:transient>

might yield:

<email>john.smith@email.com</email>

When getting the value of a message variable, the transient element does not contain any element, and the statement yields the value of the message variable. For example, the statement:

<transient name='John&apos;s e-mail' xmlns='http://www.qworum.com/' />

might yield:

<email>john.smith@email.com</email>

The following statement uses transient in order to avoid code duplication:

<qrm:try xmlns:qrm='http://www.qworum.com/'>
  <!-- Look for user in first database -->
  <qrm:call href='http://first.user-database/email_lookup'>
    <qrm:transient name='User'>
      <name>John Smith</name>
    </qrm:transient>
  </qrm:call>
  <qrm:catch>
    <!-- User not found in first database -->
    <qrm:try>
      <!-- Look for user in second database -->
      <qrm:call href='http://second.user-database/email_lookup'>
        <qrm:transient name='User' />
      </qrm:call>
      <qrm:catch>
        <!-- User not found in second database -->
      </qrm:catch>
    </qrm:try>
  </qrm:catch>
</qrm:try>

The default value of a message variable is nil.

4.9. The `try` statement

The try statement allows a message to handle a fault in order to prevent it from terminating the current call.

try statements contain one statement (the tried statement) followed by one or more catch elements. Each catch element contains zero, one or more statements.

The evaluation of try starts with the evaluation of the tried statement. If the tried statement is successful, then try yields the result of that statement. For example:

<qrm:try xmlns:qrm='http://www.qworum.com/'>
  <text>succeeds</text>
  <qrm:catch>
    <text>will never be evaluated</text>
  </qrm:catch>
</qrm:try>

yields:

<text>succeeds</text>

If the tried statement fails because of a fault, then statements in the first catch that matches the fault type are evaluated, and try yields the result of the last statement. For example, the statement:

<qrm:try xmlns:qrm='http://www.qworum.com/'>
  <qrm:fault />
  <qrm:catch types='message, user agent'>
    <text>fault is of type message or user agent</text>
    <text>0</text>
  </qrm:catch>
  <qrm:catch types='service'>
    <text>fault is of type service</text>
    <text>1</text>
  </qrm:catch>
  <qrm:catch types='service'>
    <text>fault is of type service</text>
    <text>2</text>
  </qrm:catch>
  <qrm:catch>
    <text>fault is of an undetermined type</text>
    <text>3</text>
  </qrm:catch>
</qrm:try>

yields:

<text>1</text>

The following try is unable to handle a failed tried statement, and the current call will terminate unless an enclosing try statement in the same message handles the fault:

<try xmlns='http://www.qworum.com/'>
  <fault />
  <catch types='message, user agent' />
</try>

A catch element that does not contain any statement is equivalent to one that contains a nil statement.

4.10. The `variable` statement

The variable statement is used for handling call variables, which exist throughout the duration of a service call. Call variables are used for storing call state on the client side, and they may be shared by messages of a given service call. The variable element has an attribute named name which identifies the call variable being handled.

When setting the value of a call variable, the variable element contains one statement which yields the value. The variable statement in turn yields that same value. For example, the statement:

<qrm:variable name='John&apos;s e-mail' xmlns:qrm='http://www.qworum.com/'>
  <qrm:call href='email_lookup'>
    <name>John Smith</name>
  </qrm:call>
</qrm:variable>

might yield:

<email>john.smith@email.com</email>

When getting the value of a call variable, the variable element does not contain any element, and the statement yields the value of the call variable. For example, the statement:

<variable name='John&apos;s e-mail' xmlns='http://www.qworum.com/' />

might yield:

<email>john.smith@email.com</email>

The following statement sets the value of a call variable and initiates the next phase:

<qrm:sequence xmlns:qrm='http://www.qworum.com/'>
  <qrm:variable name='Username'>
    <username>john.smith</username>
  </qrm:variable>
  <qrm:goto href='call_variable_is_set' />
</qrm:sequence>

The default value of a call variable is nil.

5. Appendices

5.1. References

[1] Berners-Lee, T., Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., and Leach, P., Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616, June 1999

[2] Berners-Lee, T., Fielding, R. and Frystyk, H., Hypertext Transfer Protocol -- HTTP/1.0, RFC 1945, May 1996

[3] Rescorla, E., HTTP Over TLS, RFC 2818, May 2000

[4] Berners-Lee, T., Masinter, L., and McCahill, M., Uniform Resource Locators (URL), RFC 1738, December 1994

[5] Fielding, R., Relative Uniform Resource Locators, RFC 1808, June 1995

[6] Extensible Markup Language (XML)

5.2. Handling non-conforming messages

The user agent transforms a received message into a message containing a fault statement of type message in the following cases:

the message is not a well-formed XML document, or
the message syntax does not conform to the present specification.

5.3. Changes between version 1.1 and version 1.2

Version 1.2 introduces:

a unified definition for Qworum messages, of which the composition and result messages of version 1.1 are special cases,
the try statement for catching faults,
the transient statement for handling message variables,
fault types.

5.4. Revision history

2008.08.24: Simplifies transient description.

2008.08.16: Initial release.

Qworum specification, version 1.2

1. Introduction

2. Service composition

2.1. Multi-phase service calls

2.2. Special case: the World Wide Web

2.3. Special case: RPC

2.4. The user agent as mediator for service calls

3. Messages

3.1. Message format

3.2. Message evaluation by the user agent

3.3. The http://www.qworum.com/ XML namespace

3.4. The application/x-qworum+xml media type

3.5. The .qrm file extension

4. Statements

4.1. The call statement

4.2. The data statement

4.3. The fault statement

4.4. The goto statement

4.5. The nil statement

4.6. The return statement

4.7. The sequence statement

4.8. The transient statement

4.9. The try statement

4.10. The variable statement

5. Appendices

5.1. References

5.2. Handling non-conforming messages

5.3. Changes between version 1.1 and version 1.2

5.4. Revision history

3.3. The `http://www.qworum.com/` XML namespace

3.4. The `application/x-qworum+xml` media type

3.5. The `.qrm` file extension

4.1. The `call` statement

4.3. The `fault` statement

4.4. The `goto` statement

4.5. The `nil` statement

4.6. The `return` statement

4.7. The `sequence` statement

4.8. The `transient` statement

4.9. The `try` statement

4.10. The `variable` statement