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 Tuesday, 16 December 2003 16:57:50 UTC