Comments on WD-ws-cdl-10-20041217

Dear Web Services Choreography Working Group,

  These are my comments on the "Web Services Choreography Description
Language Version 1.0" Last Call Working Draft [1]. Please let me know
if you intend to publish a second Last Call Working Draft before the
end of the current review period.

##

Please change the document to comply with the rules listed in Appendix C
of the XHTML 1.0 Second Edition Recommendation, see

  http://www.w3.org/mid/41ba13bd.259284953@smtp.bjoern.hoehrmann.de

for details.

##

It is not clear which sections are normative and which references are
normative, please change the document to clearly indicate normative
parts, see

  http://www.w3.org/TR/2004/WD-qaframe-spec-20041122/#norm-informative

##

The document proposes http://www.w3.org/2004/12/ws-chor/cdl as namespace
name for the language, the name is inconsistent with many other W3C
namespace names, e.g.

  * http://www.w3.org/1999/xhtml
  * http://www.w3.org/1999/xlink
  * http://www.w3.org/2000/svg
  * http://www.w3.org/2001/vxml
  * http://www.w3.org/2001/xml-events
  * http://www.w3.org/2002/xforms
  * http://www.w3.org/2004/xbl
  * ...

Please change the namespace to be consistent with these namespace names,
which will also make the namespace name much easier to use. A possible
name would be

  * http://www.w3.org/2005/cdl

##

Please do not invent yet another notation to define (or describe?) the
language elements, I encourage the Working Group to adobt the notation
in the XSLT 1.0 Recommendation, <http://www.w3.org/TR/xslt>. It is more
widely known, quite compatible to the current ad-hoc style, and in my
experience one of the best notations. Also, there are many instances of
this ad-hoc notation in the specification that seem wrong, for example,
section 2.5.5 has

  silentAction roleType="qname? />

which seems to lack a quote mark. Another problem is that e.g. "qname"
does not seem to be defined for this "informal" notation, it is thus not
well-defined whether this refers to the literal "qname" or a specific
non-terminal defined elsewhere.

##

>From section 1.1 it is also not clear what is meant by "formal" versus
"informal" definition, which definition wins if the prose, the "formal"
notation and the "informal" notation contradict each other?

##

Please put each example into a different visual block, for example in
2.4.10 two examples are in the same visual block which makes them more
difficult to read.

##

Please use different style (e.g., different background colors) for the
syntax specifications and examples, it is too easy to confuse these.

##

Many examples refer to a namespace prefix 'cdl' in XPath expressions,
yet the prefix is never declared in the examples. If processors are
expected to bootstrap the namespace, this needs to be noted in the
document (and what happens if the in-scope prefix declaration refers
to a different namespace name), if that's not required, please declare
the namespace prefix in examples.

##

I am not sure whether I miss something, but it seems most examples are
not well-formed XML, for example section 2.4.6 has

[...]
    guard="cdl:isVariableAvailable(
      cdl:getVariable("POAcknowledgement"), "", "", "tns:Customer")"
[...]

The quote marks are not properly balanced. Please either make these
examples well-formed XML or explain in the document why they are not
well-formed.

##

In the references section there are some editorial flaws such as

[...]
WS-Reliability 1.1
  , Kazunori Iwasa
[...]

Where the comma seems rather misplaced. Please removes these.

##

The lack of clearly identified normative references and the lack of a
conformance section introduce a lot of ambiguity, it is for example not
clear what the document considers a NCName. Is that an NCName as defined
in XML Namespaces 1.0 or as defined in XML Namespaces 1.1? Maybe it
depends on whether the document uses XML 1.0 or XML 1.1? Is it at all
allowed to use XML 1.1 for CDL documents?

Another example is XInclude, the document notes

[...]
  A Choreography Package aggregates a set of WS-CDL type definitions,
  provides a namespace for the definitions and through the use of
  XInclude [XInclude], MAY syntactically include WS-CDL type definitions
  that are defined in other Choreography Packages.
[...]

in section 2.2.1, but that's already clear from section 2.2.4 which
notes

[...]
  To support extending the WS-CDL language, this specification allows
  the use of extensibility elements and/or attributes defined in other
  XML namespaces. Extensibility elements and/or attributes MUST use an
  XML namespace different from that of WS-CDL. All extension namespaces
  used in a WS-CDL document MUST be declared.
[...]

So maybe the former text means that processors must support XInclude?

Another example is section 2.2.2 which notes

[...]
  A WS-CDL processor MUST ensure that the document is correct before
  processing it. The correctness may involve XML well-formedness as well
  as semantic ;checks, such as unicity of Variable definitions, of a
  single root Choreography, etc.
[...]

Well, it needs to be clearly specified what correctness involves, how
else should it be possible to implement this requirement interoperably? 

In summary, I think there is not much point in issuing a Last Call
announcement with integral parts of the specification such as the
conformance section missing.

##

There does not seem to be a MIME type for CDL documents named in the
document, if there is a registered MIME type please reference the
registration in the specification, if there is none, please follow 

  http://www.w3.org/2002/06/registering-mediatype

or the document referenced from there to register a MIME type. If it
is for some reason unreasonable to expect CDL documents to be delivered
via a protocol that supports the use of MIME types, and there is thus no
need for a MIME type for CDL documents, please state this excplicitly in
the document.

##

Please replace all occurences of "XPATH" in the document by "XPath".

##

Please change example domains to e.g. "example.org", see

  http://www.w3.org/2001/06/manual/#Examples

for details (e.g. the example in section 2.5.2.3 uses a different
domain).

##

Please consider splitting section 2 into more sections. The document
has 12 sections but section 2 is multiple times the size of all other
sections taken together which makes e.g. section numbers unnecessarily
long and sub-section headers more difficult to spot and read.

##

It seems various examples that use cdl:getVariable(...) are incorrect
as they do not specify mandatory parameters (and use weird syntax), e.g.
section 2.5.2.3 has an example with

[...]
  <send variable="cdl:getVariable(,tns:badPurchaseOrderAck,, ,,, ,,)"
[...]

which does not seem to be correct.

##

Section 2.2.4 states

[...]
  Extensions MUST NOT change the semantics of any element or
  attribute from the WS-CDL namespace.
[...]

This does not make much sense to me. Please fine a better wording for
what you mean here and provide an illustrative example for an extension
that does not conform to this requirement.

##

[1] http://www.w3.org/TR/2004/WD-ws-cdl-10-20041217/

regards.
-- 
Björn Höhrmann · mailto:bjoern@hoehrmann.de · http://bjoern.hoehrmann.de
Weinh. Str. 22 · Telefon: +49(0)621/4309674 · http://www.bjoernsworld.de
68309 Mannheim · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

Received on Friday, 17 December 2004 18:40:27 UTC