Review: RE: Arch Doc: 3 Decenber 2003 Editor's Draft

Ian,

[This is interim and I hope to complete my review ahead of the meeting - I'm
currently in section 3]

Checkpoints for the meeting:
- abstract
- status section
- 1.1.3 Principles... and REST
- 1.2.1 Orthogonal Spec.
- diagram
- 2.3 URI Ambiguity
...
- 4.5.5 Qnames in XML
  [I'm happy with this except for the comment below on the 1st GPN]

Stuart
--

Diagram:
-------
Personally like the colouring and the drop shadow. Don't like the ugly
arrows... prefer more stick like lines like the previous diagram. I would
also ask for the shape convention (or something like it) that I used
identifiers (round-cornered boxes), resources (elipses - ie as is) and
represenations (rectangles - ie. as is) - which will maintain a visual
difference even in black and white.

Typos
-----
1 Intro: list after story, item 2: Interaction "...about Web resources".
Suggest deletion. The subject of the "about" is not at all clear and it
makes sense without the "...about...".

Next sentence "...about the state of a resource through representations."
suggest "...about the state of a resource through the exchange of
representations."

item 3: asserts representation is in xhtml... however this is not apparent
in the diagram.

Next para... strike "simplest" superfluous.

1.1 About this document

1st para: "This document attempts to describe..." very british :-) I'd be
bolder (unusual for me!) "This document describes..."


1.1.2 2nd para: "This document strives..." at least for me, strive has a
connotation of failed bold attempt (may be cultural) suggest "This document
strikes a balance between brevity and precision..." or simply delete the
sentence.

Next sentence: "TAG findings..." just a two more words instead of the commas
would make it much more readable. "TAG findings are informational
documents... [which|that] complement..."

+2 sentences: delete "are expected to"... they just do evolve independently.

1.2.2 Extensibility: 3rd bullet "...open set of XML namespaces of
element..." -> "...open set of XML namespaces for element..."

Para beginning "*Language Extension: ... the handling by
implementations...". The handling of what by implementations?

2. Identification: 4th para: "Resources exist..." s/by zero URI/zero or more
URI/

2.1 URI Comparison: para beginning "Applications may..." shift parenthetical
comment to end of sentence and/or promote to being a sentence in its own
right.

2.2 URI Ownership: last para: 2nd sentence s/, as expressed through protocol
messages// I have no idea what that adds to the preceding part of the
sentence.

2.3 URI Ambiguity: last para: reword as "...because one could understand the
[identifier|phrase] 'Moby Dick' to refer to..."

2.4.1 URI Scheme Registration: Strikes me that there is a GPN missing
encouraging the registration of URI schemes.

2.5 URI Opacity: last para 1st sentence: Its not some much that specs
specifically license people deploying resources to disclose their assignment
algorithm (or schema at the risk of overloading the term). More that nothing
in general prevents folks volunteering the information and voluntarily
making a commitment to some stability of policy.

3. Interaction: 1st sentence: delete 'about resources'. ie. "Communication
between agents over a network involves URI, messages and data." Could also
lose "over a network".

Questions?/Errors
-----------------
2.4 URI Schemes: with https: what is the basis for stating "Generic URI
equivalence testing no longer works."?

2.6 Fragment Identifiers: 3rd bullet is *very* wrong. The data format
specification details fragId semantics for references *to* instances of 'F'
*not* *from* instances of 'F'. I think you could delete the 3rd bullet
without harm.

4.5.5 Qnames in XML: 1st GPN s/indistinguishable./indistinguishable from
URIs./


Themes
------
* Authority/Ownership
2.2 URI Ownership: First sentence needs some care. By a strict reading it
allows one (or 3+) agent to assign the same URI to two different resources
(but not two). I think that the crux of the matter is that the assignment
(in the sense of establish a piece of the URI->resource mapping) is by some
administrative/social/technical process delegated to a single agent - [not
actually sure we can say that - how does one determine the singularity of an
agent].

Checksums are only appropriate if representations are immutable over all
future time - unless the checksum is not maintained beyond initial
assignment... then it is just a way to generate a suitable random number.

There has been some rejection of the notion of authority and ownership, most
notably from Larry Massinter which we do not address in this draft - expect
perhaps by persisting with the notions.

* RFC2119 Terms: I still feel that we are mis-using them.

* REST
1.1.3 Last para: I would like Roy to concur that the preceding list is
indeed dervived from and consistent with his dissertation (if we are going
to claim that it is).  I also think we discussed in Japan that REST has
wider applicability than protocol designer and that its appeal should not be
so narrowly focussed.

* Orthogonality
1.2.1 3rd para... what I think this is really trying to address is
'reaching' around the recognised interfaces that a given spec/technology
provides. I'm not sure that picking on header/body separation quite makes
the point.

Bulleted list, 2nd item: I don't think that the use of META elements in HTML
and the propagation of such information to lower levels in the stack "Is a
clear abstraction violation". The use of META makes the HTML content more
self describing. It is a clear point of coupling between HTML and whatever
is carrying it (which could be SMTP). It is part of the abstraction of that
interface boundary... but I don't see it as an abstraction violation.

3rd item: Implementation failure is not necessarily indicative of
"abstraction violation" at an architectural level. It may be indicative of a
failure to communicate clearly. *If* the META information and the
Content-Type information (if present) are inconsistent then this is
indicative of an error that should not be silently ignored.

* Context free unique denotation:
2. Identification: "The scope of a URI is global: the resource identified by
a URI does not depend on the context in which the URI appears."

I'm ok with this, provided that we explain that that resource may be the
basis of an indirect identification where the referent of a sentence in
which as URI occurs may not be the resource in question, but something
related to it - in some way that depends on context.

Received on Thursday, 4 December 2003 07:26:20 UTC