[MOBY-dev] Change to the MOBY message format

[Mark Wilkinson]

Hi all, 

here's a heads-up that I am starting to implement a change to the MOBY-S
messaging format that we decided on during the last MOBY-DIC meeting. 
It is the only one of the changes that is not fully backward-compatible
with the existing message format, so I'm giving a bit of warning.

I have made changes to the Perl CommonSubs library that makes all of
this easy, and in fact, you likely wont break anything even if you
continue using the old message structure, but... it wont be "correct"
anymore :-)

Here's the description of the change:

The queryInput block(s) are now enumerated, and the queryResponse blocks
are correspondingly enumerated such that inputs and outputs may be
associated with each other Client-side.  This is accomplished through a
queryID attribute in the queryInput and queryResponse tags:

<queryInput queryID='10'>...</queryInput>

<queryResponse queryID='10'>...</queryResponse>


This replaces the two rules in the 0.5 API that said:
 
(1) outputs must appear in the same order in the response message as
they appeared in the query message, and 
 
(2) services which change the namespace of the output object must
provide an Invocation cross-reference pointing back at the originating
query.

Those two rules of the 0.5 API are now deprecated!

The value you assign (client-side) to the queryID is completely
arbitrary,and may be numeric, alphanumeric, or any other valid value of
an XML attribute.  It may also be blank, or absent (hence the backward
compatibility), but be advised that you can no longer rely on the order
of the outputs to map them back to your inputs, so... caveat emptor! 
Service providers MUST NOT try to interpret the value of the queryID
attribute; it is an opaque value that they simply copy over into their
queryResponse element.

This change was made for two reasons:  1) the Invocation object was not
sufficient to describe service inputs that consisted of Collections, or
multiple Simple articles, and 2) the ordering of outputs was a pain in
the butt for anyone providing services that did the underlying analysis
in parallel, where the outputs might become available in an arbitrary
order.

I've just finished coding the various CommonSubs routines that will make
this transition easy for the service provider, and I'm testing them
now.  As soon as they appear to be working properly (hopefully later
today) I'll commit them.  Hopefully this wont break anyone, but all
existing services will have to be updated sooner or later anyway.  

Thankfully, this was the only seriously problematic part of the existing
message format that we could identify during our discussions, so
hopefully there wont be another major change like this for a long time!

There are a few other changes to the API that we decided on, but these
are simply extensions, and will not detrimentally affect anyone.  I will
implement those over the next week or so.  Now that the Twiki has moved
over to the new open-bio server I will also update the main API
documentation so that we have a complete record of all changes.

Cheers all!

Mark

-- 
Mark Wilkinson <markw at illuminae.com>
Illuminae