Re: Comments to XQuery WG on Data Model Documentation

Norm Walsh responds to John Ibbotson:

> | Section 5.8 dm:children, once again, the description is not very 
useful.
> | The same problem exists
> | for many of the accessor descriptions in Section 6. Many of the
> | descriptions are of the form:
> | db:XXXX
> | "returns the value of the XXXX property"

> I'm somtimes uncomfortable with those descriptions too, but I've been
> unable to find better words. It's important, IMHO, to avoid having
> more than one normative description of what an accessor returns. So
> each node type defines what it returns for that node type.

I understand, but I think the spec could do a much better job of helping 
people to navigate, particularly when viewed online.  Instead of just 
saying "Returns the value of the Parent property", might one not say 
"Returns the value of the "parent property".  See section x.y.z for the 
definition of the parent property, q.r.s. for constraints on that 
property, and a.b.c for construction of parent from an Infoset." 

Maybe that's a bit too much, but a certain amount of this sort of thing 
would be very helpful I think.  I did the original pass at using the Data 
Model for our Protocols work.  I think I know generally how the DM works 
and certainly know what's intended by "dm:parent" in practice, but I found 
it very burdensome to prove it starting from the part of the spec that 
defines that accessor.

I personally think that the DM could become one of the most important 
specs produced by the Query Working group, conceivably emerging over time 
as a converged successor to Infoset, XPath 1.0 data model, etc.  While 
that remains to be seen, I think it's worth making the exposition of the 
DM as clean, approachable and precise as possible.  Thank you!

--------------------------------------
Noah Mendelsohn 
IBM Corporation
One Rogers Street
Cambridge, MA 02142
1-617-693-4036
--------------------------------------








Norman Walsh <Norman.Walsh@Sun.COM>
Sent by: w3c-xml-protocol-wg-request@w3.org
12/16/2003 04:58 PM

 
        To:     John Ibbotson <john_ibbotson@uk.ibm.com>
        cc:     public-qt-comments@w3.org, w3c-xml-protocol-wg@w3.org, (bcc: Noah 
Mendelsohn/Cambridge/IBM)
        Subject:        Re: Comments to XQuery WG on Data Model Documentation





-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

/ John Ibbotson <john_ibbotson@uk.ibm.com> was heard to say:
| In particular, the SOAP WG has found it necessary to clarify our use of 
the
| wording relating to Accessors in section 5 of [1] due to perceived
| ambiguities when used wrt the xbinc:include element for MTOM:
|
| Section 5.3 dm:node-name: It was not obvious from the Data Model
| specification
| what the syntax for this accessor should be. We eventually decided it
| should be,
| xs:Qname("http://www.w3.org/...../xbinc", "include") but this was only by
| noticing
| the example in Appendix D of the specification. We should probably have
| read the
| sections on Functions and Operators, but this was not obvious.

There is no provision for accessors that directly construct or mutate
the content of nodes. The node-name accessor returns the xs:QName that
is the name of the node.

You are correct that for the element node

  <xbinc:include xmlns:xbinc="http://www.w3.org/...../xbinc"/>

the node-name accessor would return a QName that you could construct
with xs:Qname("http://www.w3.org/...../xbinc", "include")

I'm not sure how you think the spec could be clarified.

| Section 5.4 dm:parent, the specification sates "Returns the value of the
| parent property"
| which is not a particularly useful description of the accessor. It is 
not
| clear
| from traversing the internal hyperlinks how one determines the parent of 
a
| given node.

For elements, Section 6.2.3 describes how the parent property is
specified when a data model is constructed from an infoset (and from a
PSVI if you follow the reference back from 6.2.4.)

One of the odd problems that the data model spec has is that
construction is not wholly defined by the spec. You can build a data
model *from anything* (infoset, psvi, database table, etc.) It must
only satisfy the constraints laid out by the document.

The constraints in 6.2.1 describe what constraints the parent property
on elements must obey. In particular:

  8. If a node N is a child of an element E, then the parent of N must
     be E.

  9. Exclusive of attribute and namespace nodes, if a node N has a
     parent element E, then N must be among the children of E.
     (Attribute and namespace nodes have a parent, but they do not
     appear among the children of their parent.)

     The data model permits element nodes without parents (to
     represent partial results during expression processing, for
     example). Such element nodes must not appear among the children
     of any other node.

Similar descriptions are provided for attributes and all the other
node types that have parents.

| Section 5.5 dm:string-value is fairly well specified for each node type
| (sections 6.2.2, 6.3.2)
|
| Section 5.6 dm:typed-value is also fairly well specified.
|
| Section 5.7 dm:type, the description "Returns the vaue of the type
| property" is not very useful.

That's fair, but E.7 lays out a summary by node type.

| Section 5.8 dm:children, once again, the description is not very useful.
| The same problem exists
| for many of the accessor descriptions in Section 6. Many of the
| descriptions are of the form:
| db:XXXX
| "returns the value of the XXXX property"

I'm somtimes uncomfortable with those descriptions too, but I've been
unable to find better words. It's important, IMHO, to avoid having
more than one normative description of what an accessor returns. So
each node type defines what it returns for that node type.

| A subsection of 6 (i.e., 6.1, 6.2, ...) should be read entirely to
| understand the behaviour of
| an accessor. For example, for Element Nodes, dm:children is defined as
| "returns the value of the
| children property" in 6.2.2. 6.2.1 defines some constraints over the
| children property, but does
| not define it. 6.2.3 and 6.2.4 specify own this property is constructed
| from an Infoset or a PSVI.

Right.

| Adding some links between those parts would be helpful to a reader. In 
the
| case of dm:children
| for Element Nodes, it would help to add a reference in the definition of
| dm:children for Element
| Nodes in 6.2.2 to the definition of children property in 6.2.1; and also 
to
| add some text after
| the listing of the Element Nodes' properties in 6.2.1 saying that 
building
| those properties from
| an Infoset of a PSVI is described in 6.2.3 and 6.2.4.

That's a pattern that is repeated for each node type, but I take your
point that a description would be useful.

I have tried to construct links in a way that is most useful, but
perhaps I've overlooked some access path.

If you start with a node type, the first section describes the general
constraints, the second section describes the accessors, the third
section describes how to construct from an Infoset and the fourth, how
to construct from a PSVI.

If you start with an accessor, the link to E.x provides a brief
summary of what's returned for that accessor for each node type. If
you click on the node in that list, you go directly to the discussion
of that node type.

                                        Be seeing you,
                                          norm

- -- 
Norman.Walsh@Sun.COM / XML Standards Architect / Sun Microsystems, Inc.
NOTICE: This email message is for the sole use of the intended
recipient(s) and may contain confidential and privileged information.
Any unauthorized review, use, disclosure or distribution is prohibited.
If you are not the intended recipient, please contact the sender by
reply email and destroy all copies of the original message.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.8 <http://mailcrypt.sourceforge.net/>

iD8DBQE/33+9OyltUcwYWjsRAgUgAJ9wG2Wqxj9WXVESLK2yQKxfUxNqVgCeJlSP
i7o9IM5kkISSyiKC88Ynd1I=
=qXEi
-----END PGP SIGNATURE-----

Received on Friday, 19 December 2003 10:52:30 UTC