Re-review of "Best Practice Recipes for Publishing RDF Vocabularies" (Apache cookbook)

Document re-reviewed: 
http://www.w3.org/2001/sw/BestPractices/VM/http-examples/2006-01-18/

This is a very helpful document.  I do have a few suggestions, but the
only one that I think is important enough to stand in the way of
publication (and even that doesn't *really* have to stand in the way) is
my first comment below.   Kudos to the authors!

1. Recipe 2 says it is the "simplest possible configuration", but this
is true only if the URIs have already been fixed.  (And if they have,
then it is likely that the adminstrator has already configured their
server appropriately, and thus is not in need of this cookbook.)
However, if a 303-redirect service (such as thing-described-by.org or
t-d-b.org) is used, the server configuration is clearly easier and less
error-prone, because it only requires that the server send the correct
MIME type, which the server may already do anyway.  The 303-redirect
service does the rest.  In particular, the use of a 303-redirect
service:

	- Does not require the coordinated maintenance of two URIs 
	(the original versus the forwarding location)

	- Does not require URI rewriting (except to add .rdf extension 
	if desired).

	- Does not require that MultiViews be disabled.

	- Does not require that a particular directory NOT exist.

The idea of using a 303-redirect service is quite new, and I would not
want to imply that the practice is more accepted or widespread than it
currently is -- indeed, thus far I only heard one person on a previous
teleconference say that they are using it -- but I do think it is
important to at least acknowledge it as an option, since it *is* a
simpler approach.  Perhaps something like an editors' note would be
appropriate.

2. I think it would be helpful to provide a brief "big picture" overview
of the general steps of server configuration.  This would help the
reader understand the existing recipes and be useful if the user needs a
custom configuration.  Something like the following:
[[
The general server configuration steps are:

	- Disable directory listing (if needed), so that a namespace
	URI such as http://example.org/foo/ serves a namespace document
	instead of listing the directory.

	- Set the MIME type for serving RDF/XML to "application/rdf+xml"
	(all recipes; if needed).

	- 303-redirect to the content URI (only needed for slash URIs,
	and only if a 303-redirect service is not used).

	- Add a .rdf extension (all recipes; if needed), so that
	http://example.org/foo/bar is served as
	http://example.org/foo/bar.rdf .

	- Set up content negotiation if serving both RDF and HTML
	from the same URI.

Details vary depending on the recipe.
]]

3. Section "Some considerations when choosing a URI namespace": I
suggest changing the title of this to "Choosing a namespace URI: hash
versus slash".  

4. Section "Some considerations when choosing a URI namespace":
The document says:
[[
This document is intended for creators and maintainers of existing
vocabularies. Proper guidance on choosing the best URI namespace for any
given situation is beyond the scope of this document.
]]
I think guidance on choosing between hash and slash URIs is important,
because this is such an obvious decision that someone will have to make
in conjunction with server configuration, so I suggest changing this to:
[[
Complete guidance on choosing the best namespace URI for any given
situation is beyond the scope of this document.  However, here are a few
guidelines on choosing between hash and slash URIs, since the choice
affects server configuration.
]]

5. Section "Some considerations when choosing a URI namespace":
I think it would be helpful to made the guidance more explicit, such as
adding/merging something like the following: 
[[ 
Hash URIs may be best if:

- You wish to serve your ontology as a single document and do not need
the option of breaking it up into multiple documents.

- You only need to serve RDF from your namespace URI and do not need the
option of using content negotiation to serve a human-oriented format
such as HTML from the same URI.* 

*EDITORS' NOTE: The purpose of the above consideration is to ensure
conformance to the Web Architecture[7] and the TAG's httpRange-14
decision[6].  Using content negotiation to serve both RDF and HTML would
cause the same URI reference, such as http://example.org/foo#bar , to
identify both a location within an HTML document and a concept in an
ontology, which *could* be considered a URI collision[9].  However, it
is currently unclear whether the TAG considers this to be a URI
collision or not.  (See discussion thread[10].)  If not, this
consideration can be ignored.

Pros:
	- Easy to configure.
	- Fewer URIs to maintain (one per namespace).
Cons:
	- Ontology cannot later be broken into multiple documents.
	- Potential WebArch issue if you wish to serve HTML.*  
	  (See editors' note above.)

Slash URIs may be best if:

- You want the ability to serve your ontology as multiple documents.

- You wish to serve both RDF and HTML from the same term URIs.*
(However, this consideration may not apply.  See editors' note above.)

Pros:
	- Most flexible configuration.
	- Permits the ontology to be broken into multiple 
	  documents, even to the granularity of one document
	  per term if desired.
	- New terms can be added to the ontology without 
	  modifying existing ontology documents.
Cons:
	- More complex to configure.**
	- 303-redirect requires an extra network access
	  to retrieve the ontology.**
	- Requires two URIs to be maintained in sync (original
	  URI + forwarded URI).**

** These cons can be mitigated by using a 303-redirect service such as
thing-described-by.org, however this document does not cover the use of
a 303-redirect service. 
]]

6. Many of the recipes say:
[[
# Turn off MultiViews
Options -MultiViews
]]
The comment line could be more helpful.  Does this turn off directory
listing?  If so, perhaps it could say "# Disable MultiViews (directory
listing)".  I am away from the Web as I write this, so I cannot check
the Apache documentation.

7. Recipe 3. Hash Configuration, Extended:
I don't think the comment from my previous review was addressed:
"Because the interpretation of a fragment identifier in
the presence of 303 redirects is unclear as far as I know, I think
this recipe should note that the browser may or may not apply the
fragment identifier to the secondary URI."

8. No section numbers?  I would find them helpful.  Without them it is
harder to identify a specific document section.  I remember feeling the
same lack when I reviewed the document before, though I neglected to
report it.

9. s/URI namespace/namespace URI/ throughout.

Thanks all the work on this!

References
6. TAG's httpRange-14 decision:
<http://lists.w3.org/Archives/Public/www-tag/2005Jun/0039.html>

7. TAG's Web Architecture:
<http://www.w3.org/TR/webarch/>

9. URI collision:
http://www.w3.org/TR/webarch/#URI-collision

10. Thread on using the same URI for both RDF and HTML:
http://lists.w3.org/Archives/Public/public-swbp-wg/2006Jan/0113

11. DBooth previous review of this Apache Cookbook:
http://lists.w3.org/Archives/Public/public-swbp-wg/2005Dec/0124

David Booth, Ph.D.
HP Software
dbooth@hp.com
Phone: +1 617 629 8881

Received on Wednesday, 15 February 2006 21:36:04 UTC