LC ISSUE: Editorial points

This email collects several minor editorial points regarding the WSDL
Core specification, some more minor than others.  I apologize for the
somewhat late submission, which was due to several extraneous
circumstances too tedious to mention.

    * In the paragraph at the beginning of section 1.3 ending "... the
      functionality implied by that extension is only optional to the
      client.  But it needs to be supported by the Web Service." the
      last sentence might better read "It must be supported by the Web
      Service."
    * In section 2.3.1, the paragraph beginning "Note that faults other
      than the ones described in the Interface ..." seems like more than
      a mere note.
    * In the same section, the rather long note beginning "Despite
      having a {name} property, Interface Fault components cannot be
      identified ..." seems to say, basically, that separately included
      interfaces must be consistent with each other to the extent they
      overlap.  If this is so, something to the effect of "In other
      words, interfaces must be consistent where they overlap." might
      make the situation clearer.  Also, my first reaction to this was
      "Ah, the diamond inheritance problem."  But diamond inheritance is
      not a problem, since the shared ancestor is automatically
      consistent with itself (see the note on idempotency below).  If
      I've got this right, it might be worth noting.
    * The above note appears in very similar form in other sections. 
      I'm sure that factoring this out has been suggested, but for what
      it's worth, I'd like to weigh in in favor of having at least the
      bulk of it appear only once, possibly with a short reference where
      the mostly-repeated text presently appears
    * In section 2.4.1.1, in "... the rules implied by that IRI (such as
      rules that govern the schemas) MUST be followed or it is an
      error", it was not clear to me what exactly should happen should
      this error occur.  The text appears to mean that the combination
      simply would not work, just as in-scope properties with an empty
      intersection won't work.  The question here is, what entity, if
      any, needs to report this error (and how, etc.).  Also, the net
      effect of all this seems to be the conjunction of the (possibly
      empty) set of constraints specified by the IRIs, but the
      separation into cases obscures this somewhat.  If there is a
      general agreement that this paragraph could be made clearer, I
      would be willing to attempt a clearer wording.
    * In section 2.7.1, second paragraph.  Consecutive sentences start
      with "Thus," and "Hence,"  This might flow better as "Thus, by
      definition, every SOAP 1.2 abstract feature is also a WSDL 2.0
      feature, and there is no need to define a separate WSDL 2.0
      feature ..."
    * In section 2.8.1, first paragraph, the last sentence asserts
      "Properties, and hence property values, can be shared amongst
      features/bindings/modules, and are named with IRIs precisely to
      allow this type of sharing."  This seems to emphasize that the
      names are not QNames, but it wasn't apparent to me why QNames
      wouldn't have worked equally well.  I have the distinct feeling
      the answer is blindingly obvious and I'm just missing it.
    * In 2.8.1.1, the paragraph beginning "Many of the component types
      in the component model contain a {properties} property ..."
      produced parse errors on the first couple of readings.  The root
      problem is that "property" is badly overloaded, at least in this
      context.  Unfortunately, it's not clear how to avoid this
      painlessly, as both senses of "property" are integral to the
      spec.  The upshot seems to be to distinguish between properties
      (in the F&P sense) that are directly attached (declared
      properties) and all applicable properties, whether directly
      attached or pulled in by composition (in-scope properties).  If
      this is the intent, the wording could be clearer (and again, I
      could probably have a go at rewording it).
    * In 2.9.1, paragraph 6, the text "Thus, it is an error for a
      binding component not to define bindings ..." again leads me to
      wonder what reports the error and when.  Also, the "Thus," made me
      wonder if I'd missed a step (quite likely).
    * In 2.9.2, in the XML representation of Binding components, the
      word "whgse" was clearly inserted to test whether reviewers were
      awake.  I'm happy to report that I might well be.
    * Section 2.11.2.2 seems like boilerplate in the same sense as the
      note on inheritance and overlap mentioned above.
    * In the tables in sections 2.12.3 and 2.13.3, the descriptions of
      {interface message|fault reference}seem rather lengthy for a table
      entry.  And again, they seem to be near duplicates.  The general
      problem with such duplication is of course that it's hard to tell
      without careful inspection what's duplicated and what's not.
    * In section 2.15.1, the {address} is given as optional.  Is there
      any guidance on when one might want to not include it?
    * In section 2.17, the definition of equivalence is oddly
      asymmetric.  Speaking as a math major, I'd be more comfortable if
      "and the second component has no additional properties" were
      simply "and vice versa."  Similarly, "set-based values are
      considered equivalent if they contain corresponding equivalent
      values, without regard to order." feels a bit odd since on the one
      hand, sets are unordered by definition, and on the other hand they
      are also duplicate-free by definition but this is not mentioned. 
      I might reword this as "Set-based values are considered equivalent
      if for each value in the first, there is an equivalent value in
      the second, and vice versa," parallel with the proposed rewording
      for components as a whole (and the usual set-theoretic definition
      that each is a subset of the other).
    * In the same section, in the first bullet point (simple types),
      does "contain the same value" mean "contain the same actual value"
      in the XSD sense?  If not, what does it mean?
    * In section 2.19, first paragraph, a "tuple, consisting of two
      parts" is generally called an "ordered pair".
    * In the following paragraph, "QName references are resolved by
      looking in the appropriate property," the appropriate property
      should be spelled out, even if the result is a bit tedious.
    * In 4.1, the paragraph beginning "A mutual include is direct
      inclusion by one WSDL 2.0 document of another WSDL 2.0 document
      ..." the upshot seems to be that inclusion is idempotent (because
      a component is equivalent to itself and so multiple inclusion
      doesn't redefine anything).  It would be better either to mention
      idempotency explicitly, or, perhaps better, to rephrase this
      paragraph in terms of the transitive closure (which is mentioned
      earlier) to explain that everything in the transitive closure of
      the inclusion relation is thrown into the same flat space.
    * In section 4.1, the location attribute doesn't have to be
      dereferenceable, but this may lead to unresolvable QNames down the
      line.  It would be nice to say that implementations SHOULD report
      broken location links as a root cause of the QName failures they
      cause, assuming that this is not burdensome to determine.
    * A.3 (security considerations) is remarkably short.  This is just a
      comment -- I don't think it needs to be lengthened.

Received on Wednesday, 21 September 2005 05:51:18 UTC