Here are some proposed corrections to the latest draft of the Web
Services Choreography Description Language (WS-CDL).
URL: http://www.w3.org/2002/ws/chor/edcopies/cdl/cdl.html
I've ordered them from "typos" to "stylistic infelicities." The typos
are likely to be uncontroversial, but the later categories are
probably too drastic to be useful at this stage. I'm sorry this took
me so long.
The notation for changes is
[/pre/current/=>/suggested/post/]
which means that the occurrence of pre-current-post should be changed
to pre-suggested-post. If 'current' is empty, it means that 'suggested'
should be inserted. If 'suggested' is empty, it means that 'current'
should be deleted. Sometimes this notation is generalized to multiple
'current-suggested' pairs:
[/p1/c1/=>/s1/p2/c2/=>s2/.../pK/]
Typos
In section 5.2, "Variables," and several other places, we have <ul>
lists inside <ul> lists, and apparently the stylesheets to make them
nest perspicuously are missing.
[/Note that the Variable "OrderState" at the Buyer is a different
Variable /to/=>/from/ the "OrderState" at the Seller//=>/.//]
[/also used in this Choreography, thus sharing the Variable//=>/'/s
information./]
[/A perform activity MUST bind a free Variable defined in a/=>/n/
performed Choreography/]
[/The OPTIONAL attribute free, when set to "false" specifies that
/a/=>/the/ Variable is defined in this Choreography.]
[/When this parameter is used, the /cureent/=>/current/ date information/]
[/A Variable defined in a Choreography is visible for use in this
Choreography and all its enclosed Choreographies/up-to/=>/up to/ the
point that the Variable is /re-defined/=>/redefined/ as a/n/=>//
non-free Variable, thus forming a Choreography Visibility Horizon for
this Variable./]
[/The OPTIONAL complete attribute /allows/=>/makes it possible/ to
explicitly complete/]
[/Alternatively, a Choreography in //=>/a /Successfully Completed
State/]
[/an exception causing activity is performed that has a
/causeExeption/=>/causeException/ attribute value/]
[/The actions/, including enclosed Choreographies that have not
completed, within this Choreography/=>/ within this Choreography,
including enclosed Choreographies that have not completed, /
are completed abnormally before/]
[/If more than one Finalizer Block/s are/=>/ is/ defined for the same
Choreography/]
[/Choreographies defined as requiring coordination must be/ing/=>//
bound to a Coordination protocol./]
In the CreditDecider example, the third comment is identical to the
second; it should say "B" instead of "A"
Grammatical Irregularities
There are places in the document that are simply not legal English. I
don't know how much that matters. Here is one--
[/By introducing this abstraction, a Choreography definition avoids
referencing /directly the data types/=>/the data types directly/, as
defined within a WSDL document or an XML Schema document.]
Commas Misplaced
Many sections of the document seem to follow German conventions for
comma placement instead of English ones. For instance, in English,
restrictive relative clauses must not be bounded by commas. It is
almost never correct to separate subject and predicate by a comma.
[/A Choreography in an Enabled State/,/=>// completes
unsuccessfully/,/=>// when an Exception is caused in the Choreography/]
[/The unsuccessfully completed Choreography/,/=>// enters the Closed
State/]
[/A Choreography in an Enabled State/,/=>// completes successfully
when there are no more enabled activities within its body./]
[/A Choreography/,/=>// in a Successfully Completed State/,/=>//
enters the Closed State if no Finalizer Blocks were specified in that
Choreography./]
[/A Choreography/,/=>// in a Successfully Completed State with
Finalizer Block(s) specified enters the Closed State/]
[/When Choreography Coordination is not required, then the
Choreography is not bound to a Coordination protocol/,/=>// and//=>/,/
since none of the above guarantees of agreement on the outcome
apply//=>/,/ any required coordination should/]
Stylistic Infelicities
In this version all occurrences of <code> ...</code> are gone. This
makes the document much less clear. I suppose this is some
unfortunate W3C rule.
[/The element roleType is used to identify/ the roleType of a party,
being the type of the target of an information exchange, which is then
used for statically determining where and how to send or receive
information to or into the party. Each roleType is specified by the
typeRef attribute of the roleType element.
=>/a party (named by the typeRef
attribute) that will be involved in an information exchange using this
channel./]
[/If two identity elements are specified within the same or different
channelType elements, /that/=>/and they/ have the same set of named
tokens in the same order, then they are considered to represent the
same identity type./]
[/This classification is used to indicate that this channel instance is
correlated to a previous channel instance identity,
and therefore//=> they are associated with/ the same choreography
instance./]
It's unfortunate that the word "capturing" is in the name of every
kind of variable; since it's always there, it contains no information.
Wouldn't it be cleaner to have "information-exchange variables,"
"state variables," etc.?
In sect. 5.2, the paragraph starting "The value of Variables:" is
extremely hard to understand. It's followed by three unordered
lists, most of whose elements can't follow the initial phrase.
In the first paragraph of section 5.4, we have "Variables contain
values which MAY be populated or assigned...." What's the difference
between being populated and being assigned?
[/when an Exception is caused in the Choreography and its Exception
Block/ is enabled, if present/=>/, if present, is enabled./]
[/<li>/Other types of errors/=>/Some other kind of error occurs/, such as
Protocol Based Exchange failures,/]
[/The channelVariable attribute specifies the /Channel Variable
containing information of a party, being the target of the
Interaction, which is used for determining where and how to send and
receive information to and into the party./=>/channel to be used to
communicate during the interaction.//]
(I _think_ this is the intended meaning; if not, then I have no idea
what it means.)
Why are so many of the examples laid out as single, overlong lines?