OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

legalxml-econtracts message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: review of the current draft and final requests for changes


Dear Dr Leff, Peter and TC colleagues,

Here are my comments on the draft that Peter circulated on Wednesday, 22
November 2006 at 12:28 PM (Sydney time). I have also asked my ex-DSTC
colleague, Dr Hoylen Sue (who was then our main W3C technical expert and who
is still very active and involved on the W3C schema developments) and he was
kind to provide a brief review as an independent expert. A number of his
comments are also included. Perhaps we need to find some way to thank him in
that capacity?

I separate these comments into three categories:

1. general comments, 
2. detailed comments on first section, 
3. major comments on a number of entries from the second section; note that
this last set of comments apply to the whole section, and I only give
several examples to better illustrate the nature of comment; each entry
should be given significant consideration to ensure consistency and
completeness.

Regards,
Zoran

Dr Zoran Milosevic, 
Deontik Pty Ltd.
www.deontik.com Ph:+61 410 481837



==========================================================================
Category 1: General comments

----------------------------------------------------------------

1. In a standard specification document, it is important to
clearly identify the formal specification from the
non-normative supporting material (e.g. the expository
description and examples). This document lacks a well defined distinction
between such parts. For example, I have found a number of overlaps between
fragments if text in the first 51 pages (which I assume meant to be that
non-formal part) that are repeated in the 'Dictionary'. The different nature
of non-normative and normative text is such that it is not appropriate to do
so - either something is normative or it is not. So, the document needs to
make it clear whether the supplied schema files are normative or not --
what takes precedence if they are in conflict with each
other and the spec.  Further, the formal parts of the specification
needs to be technically clear and unambiguous, which is not currently the
case (see my specific major comments below). 

May I just add that I found the document to be difficult to read in general
(but I believe Peter is addressing this as per his forthcoming review). The
current form, especially the document structure, list of authors, and
critique and referencing of other papers (e.g. last two paras in 'Precedent
Management'), has some elements of an academic paper, rather than a standard
specification. 

Also, we need to follow some OASIS criteria who is Editor, who is
Contributor of the document etc. I suggest at least looking at some other
OASIS specifications (such as SOA RM). Further, what is OASIS policy about
inclusion of technical writers in the list of authors of a document? I have
not had experience with how paid technical writers for standards are
considered in this respect (in ISO, ITU and OMG standards, a typical
practice is to have volunteers from the contributors, who accept to take on
editor roles; so, the editors are nominated, in addition to the
contributors, but there are no 'technical writers' who had no prior
involvement in standards and are only paid to do the job). 

2. Why is second section called 'Dictionary'? This is a bit unusual.
'Concept definitions' or 'Concepts' is perhaps what is more typical to a
standard spec. I assume this was meant to be normative part?

3. Table of content and some description of document structure is must for
documents like this. Also, why we have separate pagination between the first
and second part?

4. It is unclear whether the three different models (loose, standard,
and tight) are merely conventions that document authors follow, or are
modes that authoring tools can check or enforce.  If they are to be
checked or enforced, then a mechanism to identify which model is being
used is necessary. These models should be given an informal description
first (and not be the same as in the normative part). I have not found it in
the first, non-normative section.

5. As a specific reflection of point 1 above, suggest to remove details
about the schema from the expository description and put it in the normative
dictionary.  For example, the details on page 13-17.

6. The semantics of conditional processing is unclear when there are
multiple groups.

e.g. 
   <metadata>
     <conditions>
       <group><name>USA states</name>
         <condition name="CA"/>
         <condition name="NY"/>
         <condition name="NV"/>
         <condition name="WA"/>
       </group>
       <group><name>Australian states</name>
         <condition name="QLD"/>
         <condition name="NT"/>
         <condition name="WA"/>
       </group>
     </conditions>
   ...

   <block condition="WA">...</block>

How do I distinguish between Washington and Western Australia (both of which
have WA above? 

How is the "name" of the group ever used?

The type of the condition attribute as xsd:string allows whitespace,
which creates problems.

Hoylen suggested this to address the problem:


     <conditions>
       <group><name id="usa">USA states</name>
         <condition name="CA">California</condition>
         <condition name="NY">New York</condition>
         <condition name="NV">Nevada</condition>
         <condition name="WA">Washington State</condition>
       </group>
       <group><name id="aus">Australian states</name>
         <condition name="QLD">Queensland</condition>
         <condition name="NT">Northern Territory</condition>
         <condition name="WA">Western Australia</condition>
       </group>
     </conditions>
   ...

   <block cond-group="usa" cond-value="WA">...</block>



7. What is the intent of 'inclusion'. Is it for example different than
semantics of XInclude (I suspect not). If not, then, do not attempt to
redefine the semantics XInclude (and also nDublin Core elements) in this
document.  Either reference those specifications, or give your elements
different names for them.

8. A related point to the previous one is a need to include a list of
namespaces that this document relies on. This may be at the beginning of the
second part of the spec. 

9. What happens if field names are not unique in a document?  This is
fine for inputting into a form, but not for extracting from a form. For
example, what to do in case of more than one party to the contract :-)

10. Consider identifying fields with URIs instead of just textual
names.  This will help guarantee uniqueness in a global environment.

11. Is there any reason why only a subset of Dublin Core is permitted?

12. The "real world example" should be removed from this specification
document; or minimally move it into a non-normative appendix and fix
the line truncations in it.

13. The section on the supplied schemas (p. 40-42) needs to be clearly
identified as a normative part of the specification or non-normative.
Currently it is unclear whether the dictionary takes precedence over
the schemas (and which schemas if they are in conflict).

14. It should clearly state the customizations are no longer compliant
with the standard, and how those customized documents can be
differentiated from standard documents (e.g. new namesace).

15. The dictionary lacks detail about the semantics of the attributes.

16. The "content model" sections of the dictionary are incorrect in
many places (mostly in the ones that allow text or mixed content
models).  A more compact notation would be welcomed (consider the
notation XQuery 1.0, WSDL 2.0 specification, or DTD uses). This is a serious
concern !

17. The "children" sections of the dictionary duplicate the
information in the content model section (or worse, contradict it).
Suggest dropping the "children" sections.

18. What is 'class' (entry 7, on page 21 used for?)

19. Do we need to have any comment about 'digital signatures' in the
introduction? I am sure there would be questions about it and it would be
good to clarify our current and future intent re this.

20. Is it appropriate to mention BNML on p. 30? This seems to me that was
taken straight out of a previous document, but I don't think that these
details appropriate for the standard. It is good that we already have a
complaint schema with this future standard, but I don't think this should be
made explicit in the document. 

21. We need a clear description o background material, i.e. XML Schema,
RelaxNG, what we are using and rationale for either or both.

22. A more normative form of the previous point are the compliance
statements, i.e. which standards does this e-contracts standard make use of,
or in other words, what are compliance statements in our standard, as well
as conformance points (which are different than compliance; they refer to
how one can determine whether products claim to satisfy the standard); so
MUST have two separate sections: compliance and conformance. Further, many
standards also include a set of requirements at the very beginning, so we
may consider listing in a very succinct form the requirements that Peter and
me later (with the focus on 'field' element) have put together. 

23. 'Structure of the Schema Files" (p 41). Is this normative? This again
highlights need for clear statement of what parts of this standard would
expected to be conformant to.

----------------------------------------------------------------

Category 2:  (on the first section)

In several places, sentences start with "E.G." (5th paragraph on page
6, top of page 6).  These should be spealt out in full as "For
example".

Is there a reason why the element is called "contract-front", but the
body and back are not "contract-body" and "contract-back"?  For
consistency, I would think that it should be simply called "front".

Example 2, if it is supposed to be an absolute minimal contract, could
be written with an empty title.

Example 2 could probably be simplified to remove the Dublin Core and
XInclude namespaces.

Page 8, 4th last line, typo: "contains the dates _adn_ a list".

Bottom of page 8, says "The body shows how text is prepared using the
standard model."  This sentence does not make sense. The body doesn't
show anything, it is used to represent text.

Bottom of page 8, it is unclear at this point what a "tight or loose
model" is.

Page 9, "blueprint" should be one word, not two.

Page 9, says "Lastly the back at the end illustrates the
party-signature element" which is a strange thing to say.  It doesn't
"illustrate" it.

Page 9, Line 14 of example 3 does not fit on the page and is
truncated.  The same problem applies to most of the signature
examples. Those signature examples are very hard to read because they
are all compacted together.

Page 10, third last line, the quotes should not be around "model".

Page 10, the sentence in the middle about valid text containers is
incomplete.
It is unclear whether these are all the text containers, or just some of
them.

Page 12, paragraph 1, is unclear about what is permitted to be nested
inside the top level block or item elements.

Page 13, line 1, incomplete sentence missing closing parenthesis.

Page 13, line 2, why does it say rendered by "disc or bullet" and not
just "bullet"?  Does it matter?  Same for "line or dash" (which sound
like the same thing).

Page 13, why does "line" and "none" have no "SHOULD" requirement on
the application programmer.  The other items in the list do.  Also
"manual" inconsistently places a requiremet on the contract writer and
not the application programmer.

Page 13, the previous section on numbering clearly said the rendering
"SHOULD" be done.  It would be good if the same rigour was used in the
description of in-line text elements.  

Page 14, Example 8, the characters in the sup elements are displayed
incorrectly.

Page 14, says "the text may contain phrase" is uninformative.

Page 18, the text used in example 12, 13, and 14 are confusing.  For
example, one block of text says "only this block will be included"
when it is clear that the example is showing that other blocks will
also appear depending on the condition value.

Page 19, id attributes: Has the use of xml:id been considered? 
<http://www.w3.org/TR/xml-id/>

Page 20, field: defining only two scenarios and saying that fields
shall be used in these cases is restrictive.  This section should
simply describe what the field mechanism does, and provide the
scenarios as examples of how it can be used.

Page 24, align-records: this seems an odd feature to have since it is
the only part of the specification that deals with layout issues.

Page 24, brace attribute: this is described as rendered on the right
side.  Is this always the case?  Perhaps contracts written in
right-to-left languages (e.g Hebrew, Arabic) want it on the left side?

Page 30, real world example, this should be removed from the
specification itself, or at least moved into a non-normative appendix.

Page 49, "Milosovic" should be "Milosevic", and "Deontic.com" should be
"Deontik Pty Ltd". 


----------------------------------------------------------------
Category 3:

This section require careful reading and significant changes to ensure
compliance with other standards that which e-contracts makes use of, and
completeness. Below are several detailed comments on some of the entries in
the dictionary. [I assume that Peter is also working on this, base on his
earlier email]

text

 - The content model does not say that the text element can contain
 mixed content.  In fact, saying it just contains a choice is incorrect.
Choice implies 'one-only'. Why don't we use xsd: string ?

 - It seems a bit strange that the text has a "textflow" attribute,
 instead of simply relying on the use of "block" to control line
 breaking.  Could the need for this design feature be briefly
 described?  It could make rendering a contract more difficult than it
 needs to be (because lookahead will be required).

 - The mixture of "text" and "note" and "note-in-line" in the presence
 of the textflow attribute is unclear.  For example, it is unclear
 whether these pairs are are different or not:

  <text>alpha <text>beta</text> gamma</text>
  <text>alpha <text textflow="runon">beta</text> gamma</text>

  <text>alpha <note>beta</note> gamma</text>
  <text>alpha <note>beta</note> <text textflow="runon">gamma</text></text>


 - xml:space is an attribute from the XML specification, and its usage
 should not be constrained in this manner.  And certainly its
 definition should not be described here in this manner, which is not
 very precise -- simply refer to the XML 1.0 specification if needed.

 - the formatting of the "parents" section is confusing, since some
 terms are in monospace fonts and others are not.


title

 - it is not obvious why one would use a title with zero text
 elements, or more than one text element.

 - The minimal contract examples are incorrect, because they have one
 text element in the title, whereas the minimal example does not need
 to contain any text elements.

subtitle

 - The "children" for the subtitle element does not match the
 described content model.

 - It seems strange why subtitle does not simply have the same content
 model as title (i.e. containing text elements).  Is there a reason for
this?


sub and sup

 - It seems strange that only certain elements are allowed directly
 inside a sub/sup (e.g. em, field, strike).  It appears that this is
 done to restrict the types of elements that are allowed.  However,
 since "text" is also allowed in sub/sup, this restriction doesn't
 work.  For example, the following are allowed:

 <sub>alpha <text><note>beta</note></text> gamma</sub>

 <sub>alpha <text><object> ...</object></text> gamma</sub>

 - It is unclear what is the semantic difference between:
       <sub>foobar</sub> and
       <sub><text>foobar</text></sub>
       <sub><text>foo</text><text>bar</text></sub>

  - The content model for sub and sub does not indicate that mixed
  content is allowed in these elements, even though the intention is
  that it is.


item (outside of a block)

 - content model seems incomplete

Field
 - we need to be clear what types this standard will support; is this
integer, string, current only? Or should we restrict this to be any simple
XML Schema type? I would go for the latter, but this requires further
discussions






[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]