[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]