comments on the LC draft of DCI (http://www.w3.org/TR/dpf
) which were
not sent to the public mailing-list.
Agreement made by the author
-------- Original Message --------
Hi DI WG,
you have requested review from the Web APIs WG, but
unfortunately the
WG only just started and only few members have already
joined, making
it highly unlikely that we will be able to provide feedback
as a
group. I have however passed on your request to those who
have
already joined, and you may get feedback from individual
participants. This is mine, and does not represent the
consensus of
any group (but I'm Cc'ing Web API nevertheless so as to
avoid
duplication).
To summarise my personal opinion, I feel that the DCI
specification
is conceptually sound and useful in purpose, definitely
something
that I look forward to using in the field. However, I have
found
substantive technical issues that require modifications to
the draft,
and, unless I have misunderstood parts of the current draft,
would
normally warrant return for further work. Please find the
detail of
my comments below.
:: Issues ::
- Why have the nodeValue be the string "NULL"
and not simply have
the null value as is usually the case for Nodes that don't
have a
value? This breaks some assumptions that implementations can
make and
might increase footprint for no obvious (from reading the
draft) gain.
- The valueType attribute is open-ended in what it can
contain but
you don't describe how vendors should name their types,
which in turn
may lead to type name clashes. You should probably recommend
that
vendors name their extensions using IRIs (this doesn't mean
you have
to use IRIs yourselves, you can claim that you are the only
source
allowed to use plain strings). Also, why is this NULL (or
null) for
DCIComponents?
- Same comments for propertyType and
DCIMetaDataInterfaceType (for
the latter, unless it is always a media type, in which case
this
should be specified).
- While the "any" type *might* make sense for
a value since it
could be a simple value (e.g. an int) just as well as an
object, is
that the case for DCIMetaDataInterface? Wouldn't it always
something
more structured than a simple value, say at least a string?
- *Please* don't use null to indicate a wildcard for
namespaceURI
or propertyName. This is different from the way the DOM does
it, and
can cause confusion as to what describes properties in no
namespace.
Use the star instead ('*') as the other specificiations
do.
- Is there really a need to have both searchProperty and
hasProperty when they are so close? Experience shows that as
soon as
you add a convenience method to an API, users will clamour
for a
zillion others such as searchForDogFoodProperty and
getAnArmForAHandProperty. If convenience methods are needed,
they are
best introduced in a second version based on experience from
what
users find difficult to do (or what is inefficient to
implement), as
for instance DOM 3's textContent.
- There is confusion regarding what exceptions are to be
raised,
DOMException or DCIException. You can't reuse DOMException
to add
your own exception codes because that is highly likely to
clash with
future extensions to the DOM, therefore DOMExceptions must
only be
raised when an existing exception as specified in the DOM is
raised,
for all other uses a DCIException (which could wrap a
DOMException)
has to be used. It's unclear from the draft which is which.
The IDL
only ever mentions DOMException with values it doesn't have
(and
using the strange
"raises(DOMException::FOO_ERR)" instead of just
"raises(DOMException)" with the prose saying
which codes may apply)
and doesn't define DCIException (!) while other parts talk
of
DCIException. Please change the draft to define the latter
and to use
it when DOMExceptions don't apply.
- I have trouble understanding the relationship between a
DCI DOM
tree and a DOM tree representing an XML document. You extend
Node
directly, thereby creating new node types (which is a major
issue, as
future versions of the DOM itself may themselves need to add
node
types, in which case you would be clashing with them -- this
is *not*
a theoretical problem, you are already clashing with DOM 3
XPath[0])
but you don't clearly define the behaviour of these nodes
when other
DOM operations are applied to them. What happens if someone
tries to
serialise that DOM? What are the nodeName, baseURI,
attributes,
childNodes, first/lastChild, next/previousSibling,
ownerDocument,
prefix, or textContent set to for DCI nodes? What happens if
I try to
append a DCI node as the child of an element or attribute
node in the
DOM, or vice-versa? What happens when I call cloneNode,
compareDocumentPosition, getFeature, getUserData,
isEqualNode,
lookupPrefix, etc. on them? The DOM defines this for the
types which
inherit from Node, but you don't, which potentially opens
the door to
interoperability issues as much is left to implementations.
I would
recommend either a) clarifying the relationship to the DOM
(which may
constitute major work and is an error-prone process), b)
removing the
inheritance from Node (this requires checking that events
would still
work, but so long as you inherit from EventTarget I think
you're
fine), or c) defining the DCI tree as a tree of elements
(which may
never be serialised as XML), and therefore inheriting from
Element
(this has the advantage that they can be dumped as XML
easily, but
may have issues in that you would have to specify what
happens if a
DCI element is imported into another document). I think that
option
(b) is likely to be the one that will remove the largest set
of
issues with minimal work, especially since you don't seem
to be
making much use of the fact that you inherit from Node,
apart from
reusing a few fields.
:: Editorial issues ::
- Section 2 point 5 has "To be discussed 16th Sept
f2f". I assume
you don't want that in your CR document 
- Section 3 is a bit wooly, using terminology like
"this will build
upon the types defined by the W3C DOM working group"
(is it not done
already?) or "some of the common data types in the DOM
include" (is
the list exhaustive or not?). It would be best to make the
list
exhaustive so that implementers immediately know what they
need to
reuse from the DOM, even if the definitions for the types
are left to
another specification.
- You define DOMString as "a Unicode string encoded
with UTF-16". I
would drop the "encoded with UTF-16" since while
that's pretty much
what the DOM and the IDL prescribe, it is something that
language
specific bindings typically override as an implementation
detail
(many languages map DOMString to their native string
constructs,
which are often in UTF-8 internally, even though they can
always
produce UTF-16 on request).
- This is unclear: "the DOM NodeList interface when
used within the
DCI context would return a DCIProperty instead of a DOM
Node". I
suppose that you mean that NodeList::item() returns a
DCIProperty
instead of a Node? That's somewhat wrong as in most
languages that
enforce some notion of typing it won't be possible to have
that
method return a type instead of another. I think you'd be
better off
saying that NodeList::item() must return Nodes that can be
casted to
DCIProperties, or something along those lines. Also,
wherever that's
the case it needs to be specified normatively (i.e. not in a
sentence
that starts with "for example").
- Unclear as well (in 4.1): "This is independent of
the event
propagation model in the host environment." I think
you mean that if
the host environment dispatches events through carrier
pigeons and
therefore only supports the "flying/cooing event
propagation model"
it still needs to support bubble/capture for DCI, but it
could be
expressed more clearly. Also, have you considered making the
capture
phase optional? Some other DOMs already do that (for
instance the SVG
MicroDOM). The capture phase adds implementation overhead
for no
obvious value (IMHO).
- You consistently use the word "metadata"
(which seems fine to me)
yet you called the corresponding interface
"DCIMetaDataInterface",
capitalising the 'D' which suggests that it's really
"DCI Meta Data
Interface". CamelCase is already somewhat hard to
guess, especially
for non native speakers, so being consistent and calling it
"DCIMetadataInterface" is probably best.
- In some places you state that some attributes need to
have the
value NULL, where it's unclear whether that's the string
"NULL" (as
for nodeValue) or the null value. If the former then please
consider
using the latter instead, and if the latter then the normal
way of
flagging it in W3C specifications is to use
<code>null</code>
(lowercase).
- 5.1.2.1 "This method is used to determine whether
this property
has a given named property". I find this quite hard to
parse, maybe
you should tag "in its descendants" at the end?
- In 5.3, you seem to indicate that the version is a
string that
has to be "1.0" (for this version), entailing
that "1", "1.0.0", etc.
are invalid and compare differently. Experience shows that
if you
don't state this in excruciating detail people *will* get
it wrong
and perform numeric comparisons.
- In B.2 you use the text/javascript media type which is
deprecated
in favour of application/ecmascript. Also, there is no NULL
object,
just null (though since it hasn't been declared it'll
resolve to
null, but it's still bad practice). If the document intends
to be
XHTML (which it looks to be from the XMLDecl and the
namespace) then
it MUST include the relevant DOCTYPE (yes I know that's
terrible, but
complain to the HTML WG . The
second script element seems to add a
listener to the head element, it's unclear to me that this
element
ever sees that event.
::Nitpicks::
- The ob-RFC2119 reference "In this document the key
words must..."
is placed in the introduction, which I assume to be
informative. It
might be best to place it in the conformance chapter.
- You mention "cell phones", AFAIK this is an
americanism to which
the more generic "mobile phone" (or device) is
generally preferred.
- You talk of "URIs". The terminology this
week is "IRIs".
- When including a diagram, it's nice to also provide an
SVG version.
- "a NodeList with length attribute value of
Zero": no need to
capitalise Zero.
- "If the return value is true, the node is included
otherwise, the
node is rejected" should be "If the return value
is true the node is
included, otherwise it is rejected."
::Questions::
- Do you plan on defining a metadata interface more
completely in
the future, or is that completely left up to other
specifications?
- It seems to me that using the IDL "any" type
may cause
compatibility issues with some languages, do you have a
rationale for
not using DOMObject there?
[0]http://www.w3.org/TR/DOM-Level-3-XPath/xpath.htm
l#XPathNamespace
--
Robin Berjon
Senior Research Scientist
Expway, http://expway.com/
--
Stephane Boyera stephane w3.org
W3C +33 (0) 4 92 38 78 34
BP 93 fax: +33 (0) 4 92 38 78 22
F-06902 Sophia Antipolis Cedex,
France
|