Configuring Apache HTTP Server for RDFS/OWL Ontologies Cookbook

@@rrs: better title wanted: perhaps "Best Practices for Serving RDFS and OWL Vocabularies"

Editor's Draft 18 November 2005 [revised]

This version:

http://www.w3.org/2001/sw/BestPractices/VM/http-examples/2005-11-18/
--- $Id: Overview.html,v 1.17 2006/01/18 20:19:17 ajm65 Exp $ ---

Latest version:

http://www.w3.org/2001/sw/BestPractices/VM/http-examples/

Previous version:

None.

Editor:

Alistair Miles, CCLRC Rutherford Appleton Laboratory

Copyright ©2005 W3C^® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

---

Abstract

When a new RDFS vocabulary or OWL ontology is created, the author has several choices about naming the new resources. These choices are not arbitrary; they interact with Web architecture [AWWW04] in ways that may not be immediately apparent. This document describes several recipes for publishing an RDFS vocabulary or OWL ontology in the Web. the special considerations appropriate to each recipe are described so that the vocabulary or ontology creator may choose one of the recipes according to the needs of his or her particular situation. All of the recipes here are designed for use with an Apache HTTP server, though the principles involved may be adapted to other environments.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications can be found in the W3C technical reports index at http://www.w3.org/TR/.

Here Be Dragons!!!

This document was prepared by the Vocabulary Management Task Force of the Semantic Web Best Practices and Deployment Working Group. This document is an Editor's Draft, prepared for discussion prior to Working Draft publication. It has no formal status within the W3C process. After additional review within the Working Group, the Task Force expects to seek Working Group consensus for publication of this document as a W3C Working Draft.

Comments are welcome. If you have problems with these configurations, or believe them to be incorrect, please send email to public-swbp-wg@w3.org (start subject line with '[comment]'). All messages sent to this address are available in a public archive.

Contents

• Introduction
• A Note on Apache Configuration
• A Note on Namespace Naming
• Choosing a Recipe
• Recipe 1. Hash Configuration, Minimal
• Recipe 2. Slash Configuration, Minimal
• Recipe 3. Hash Configuration, Extended
• Recipe 4. Slash Configuration, Extended, Single HTML Document
• Recipe 5. Slash Configuration, Extended, Multiple HTML Documents
• A Note on PURLs
• Recipe 6. PURL Hash Configuration, Minimal
• Recipe 7. PURL Slash Configuration, Minimal
• Recipe 8. PURL Hash Configuration, Extended
• Recipe 9. PURL Slash Configuration, Extended, Single HTML Document
• Recipe 10. PURL Slash Configuration, Extended, Multiple HTML Documents
• Requirements
  • Minimum Requirements
  • Extended Requirements

• Acknowledgements
• References

Introduction

The author of a new RDFS vocabulary or OWL ontology [hereafter this document will refer to both as simply vocabulary] has several choices for naming the new resources defined by the vocabulary. Some of these choices have important implications for future management of the vocabulary's namespace. A few minutes spent thinking about the likely future evolution of the vocabulary when the names are first chosen can avoid some later difficulties.

The example configurations described in this cookbook are intended to cover most of the common cases and guide the vocabulary creator to a design that is considered good practice and consistent with architectural principles of the World Wide Web and of the Semantic Web. There are 10 recipes described here. The first 5 cover typical cases and the last 5 discuss special considerations when using a widely-deployed "persistent URL" service. Vocabulary creators who have long-term ownership of a part of Web address space within a chosen Internet domain need only look at recipes 1-5. Vocabulary creators who anticipate a need to move the actual information resource artifacts (i.e. the Web documents) underlying the vocabulary from a server in one domain to a server in a different domain may wish to investigate the (free) address redirection service offered by PURLs [PURL]. Recipes 6-10 are extensions to recipes 1-5 for use with the PURL service.

As a vocabulary author, you should choose the example configuration below that most fits your needs and adapt it for your ontology.

N.B. These configurations implement some or all of a set of requirements, which are described at the end of this document. The requirements are intended to be an articulation of good practice, which can be verified independently of the implementation, and against which the configurations can be tested.

N.B. The configurations given here have been tested on an Apache 2.0.46 only.

A Note on Apache Configuration

An Apache HTTP server [APACHE] is configured by directives written either inside the main Apache configuration files (usually 'httpd.conf' etc.) or inside per-directory configuration files (usually '.htaccess'). The recipes given here assume that you do not have access to the main Apache configuration files and that you therefore have to use per-directory '.htaccess' configuration. In order to support this use of per-directory configuration files the server must be configured to allow certain overrides for the directories you are using. The required overrides are:

AllowOverride FileInfo AuthConfig Limit Options Indexes
@@TODO verify minimal required overrides

If you are having problems getting the recipes to work, it may be because the required override directives are not specified in the main Apache configuration files. If you are unsure about this, contact your server administrator.

If you do have write access to the main Apache configuration files, you might consider writing the following recipe directives directly in there, as using per-directory configuration has some consequences for server performance, see [@@TODOREF].

N.B. the appropriate content type for serving RDF/XML content is 'application/rdf+xml'. An Apache server can be configured to recognise files with the '.rdf' extension, and serve them with the appropriate content type, by adding the following directive to the main configuration file:

AddType application/rdf+xml .rdf

If you do not have write access to the main Apache configuration file, you can also include this directive in a per-directory configuration file, as shown in the following examples.

A Note on Namespace Naming

The namespace name you choose for your vocabulary should be a Web address (a URI) to which you have write access. Others who use your vocabulary will expect to be able to dereference both the namespace URI itself as well as the URIs of properties and classes in your vocabulary. The URIs of the properties and classes in your vocabulary are defined to be the concatenation of the namespace URI with the individual property or class name. Therefore the choice of namespace URI is a fundamental decision you make early in the design of your vocabulary.

While RDF permits a namespace name to start with any valid URI scheme, best practice for the Semantic Web is to use a URI scheme that can be resolved by any client without requiring the use of additional plug-ins or client setup configuration. The http URI scheme is the best known of these and is recognized by all Web clients. This document focuses exclusively on vocabularies whose namespace name begins with http: unless otherwise stated.

Best practice dictates that all RDF namespace URIs end in either "#" or '/'. Which you choose depends in part on how big you expect your vocabulary to become, how often you expect to add new terms (i.e. properties or classes) to your vocabulary, and how you expect users to access information about individual terms in your vocabulary.

A vocabulary that is small and whose terms are all likely to be wanted by most users might be most conveniently arranged so that most or all of the vocabulary definitions are retrievable in a single Web access. The namespace name for such a vocabulary would typically end in '#' and a Web access (i.e. HTTP GET request) for any term in the vocabulary would return a single information resource that would describe each of the terms in the vocabulary. For convenience here, a namespace whose name ends in '#' is called a hash namespace.

A vocabulary that is very large, to which additions are anticipated frequently, or that defines more data than a typical user application will want to access at one time should be arranged so that progressively greater detail about the terms in the vocabulary are retrieved through multiple Web accesses. The full description of all of the terms is divided among many information resources, each of which has the namespace URI as its root. The namespace name for such a vocabulary would typically end in '/' and a Web access for any term in the vocabulary would return information principally about just that one term. In this document a namespace whose name ends in '/' is called a slash namespace.

For a vocabulary defined using a hash namespace, the namespace URI will be something like:

http://www.example.com/foo#

and the URIs of classes and properties defined by that vocabulary will be something like

http://www.example.com/foo#MyClass
http://www.example.com/foo#myProperty

The fragment identifier that is appended to the namespace URI is also known as the local name of the class or property.

For a vocabulary defined using a slash namespace, the ontology URI will be something like

http://www.example.com/bar/

and the URIs of classes and properties defined by that vocabulary are again formed by appending the local name of each term; the resulting term URIs will be something like

http://www.example.com/bar/MyClass
http://www.example.com/bar/myProperty

Both 'hash namespaces' and 'slash namespaces' are supported within the architecture of the Web however certain behaviours are required of the Web server that differ between these two choices. Because both the request(s) received by the server and the responses returned by the server are different, the mechanics of setting up an HTTP server to satisfy some or all of the requirements given below differ between 'hash' and 'slash' namespaces.

The recipes below describe how to configure an Apache server so that it returns the appropriate responses given a specific choice of namespace name. For brevity, the rationale behind each recipe is not described here. Readers who wish to investigate the rationale should familiarize themselves with URI/Resource Relationships in [AWWW04], fragment identifiers in HTTP URIs [RFC3986] [RFC2616], and the W3C Technical Architecture Group's resolution on the range of HTTP dereferencing (aka "httpRange-14").

Choosing a Recipe

The choice of recipe depends in part on what types of content you wish to provide at your namespace URI and on the URIs of the terms in your vocabulary.

Simple Configuration

The simplest recipes configure your server to provide only machine-readable (RDF) content.

If you are using a hash namespace and do not need to serve human-readable content, see recipe 1 or, if using PURLs, recipe 6.

If you are using a slash namespace and do not need to serve human-readable content, see recipe 2 or, if using PURLs, recipe 7.

Extended Configuration

The extended recipes configure your server to serve both machine-readable (RDF) and human-readable (HTML) content at your vocabulary URIs. These recipes are easily extended to serve additional formats.

If you are using a hash namespace and want to be able to serve both RDF and HTML, see recipe 3 or, if using PURLs, recipe 8.

If you are using a slash namespace and want to be able to serve both RDF and HTML content where the HTML content is contained in a single document, see recipe 4 or, if using PURLs, recipe 9.

If you are using a slash namespace and want to be able to serve both RDF and HTML content where the HTML content is served in individual hyperlinked documents with an overview (e.g. a table of contents or an index) at the namespace URI, see recipe 5 or, if using PURLs, recipe 10.

Recipe 1. Hash Configuration, Minimal

This recipe gives an example of the simplest possible configuration for an ontology that uses a hash namespace. The recipe configures the server to provide machine-readable (RDF) content from the ontology URI, thereby satisfying the minimum requirements. This is illustrated by the following diagram:

Example Configuration

For ontology with URI

http://isegserv.itd.rl.ac.uk/VM/http-examples/example1

... defining classes ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example1#ClassA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example1#ClassB

... and properties ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example1#propA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example1#propB

...

Step 1

Create a file called example1.rdf that contains a complete RDF/XML serialisation of the ontology. I.e. all resources defined by the ontology are described in this file.

Step 2

Copy the example1.rdf file to the /apachedocumentroot/VM/http-examples/ directory on the server.

Step 3

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/directory on the server ...

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to serve RDF/XML content from the namespace URI
RewriteRule ^example1$ example1.rdf

(N.B. If a .htaccess file does not exist, create one.)

Testing the Configuration

If this configuration is working, it should support the following interactions ...

GET /VM/http-examples/example1 HTTP/1.1
Host: isegserv.itd.rl.ac.uk

HTTP/1.x 200 OK
Content-Type: application/rdf+xml

Recipe 2. Slash Configuration, Minimal

This recipe gives an example of the simplest possible configuration for an ontology that uses a slash namespace. The recipe configures the server to provide machine-readable (RDF) content from the ontology URI, and to redirect the client to the ontology URI from class and property URIs, thereby satisfying the minimum requirements. This is illustrated by the following diagrams:

Example Configuration

For ontology ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example2/

... defining classes ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example2/ClassA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example2/ClassB

... and properties ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example2/propA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example2/propB

...

Step 1

Create a file called example2.rdf that contains a complete RDF/XML serialisation of the ontology. I.e. all resources defined by the ontology are described in this file.

Step 2

Copy the example2.rdf file to the /apachedocumentroot/VM/http-examples/ directory on the server.

Step 3

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/directory on the server ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to redirect 303 from any class or prop URI
RewriteRule ^example2/.+ example2/ [R=303]

# Rewrite rule to serve RDF/XML content from the namespace URI
RewriteRule ^example2/$ example2.rdf

(N.B. If a .htaccess file does not exist, create one.)

The directory option 'MultiViews' must be disabled for this configuration to work, and a directory called /apachedocumentroot/VM/http-example/example2/ must not actually exist on the server's file system.

Testing the Configuration

If this configuration is working, it should support the following interactions ...

GET /VM/http-examples/example2/ HTTP/1.1
Host: isegserv.itd.rl.ac.uk

HTTP/1.x 200 OK
Content-Type: application/rdf+xml

GET /VM/http-examples/example2/ClassA HTTP/1.1
Host: isegserv.itd.rl.ac.uk

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example2/

Recipe 3. Hash Configuration, Extended

This recipe gives an example of an extended configuration for an ontology with a hash namespace. The recipe configures the server to provide either human-readable (HTML) or machine-readable (RDF) content from the ontology URI, depending on what is requested, thereby satisfying the extended requirements. This is illustrated by the following diagrams:

Example Configuration

For ontology ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example3

... defining classes ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example3#ClassA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example3#ClassB

... and properties ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example3#propA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example3#propB

...

Step 1

Create a file called 2005-10-31.rdf that contains a complete RDF/XML serialisation of the ontology, as at 2005-10-31 (or whatever the current date is). I.e. all resources defined by the ontology are described in this file, and this file represents a 'snapshot' or 'version' of the ontology.

Step 2

Create a file called 2005-10-31.html that contains HTML content documentation about all classes and properties defined by the ontology as at 2005-10-31 (or whatever the current date is). This document may include sections for each of the classes/properties documented, each section being headed by an HTML anchor whose name is identical to the fragment identifier of the documented class/property.

Step 3

Copy 2005-10-31.rdf and 2005-10-31.html to the directory /apachedocumentroot/VM/http-examples/example3-content/ on the server.

Step 4

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/ directory ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to make sure we serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example3$ example3-content/2005-10-31.html [R=303]

# Rewrite rule to make sure we serve the RDF/XML content from the namespace URI by default 
RewriteRule ^example3$ example3-content/2005-10-31.rdf [R=303]

(N.B. If a .htaccess file does not exist, create one.)

Testing the Configuration

If this configuration is working, it should support the following interactions ...

GET /VM/http-examples/example3 HTTP/1.1
Host: isegserv.itd.rl.ac.uk
Accept: text/html

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example3-content/2005-10-31.html

GET /VM/http-examples/example3 HTTP/1.1
Host: isegserv.itd.rl.ac.uk
Accept: application/rdf+xml

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example3-content/2005-10-31.rdf

Notes

This example uses the modification date of the ontology version to create file names. It would also be possible to use version numbers (e.g. '1.01') instead of dates for this purpose, or indeed any convention that makes it possible to differentiate between ontology versions, and helps to keep track of version history.

Recipe 4. Slash Configuration, Extended, Single HTML Document

This recipe gives an example configuration that satisfies the extended requirements for an ontology with a slash namespace.Both machine-readable (RDF) and human-readable (HTML) content is served at the namespace URI. The HTML documentation is served as a single file.

For ontology ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example4/

... defining classes ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example4/ClassA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example4/ClassB

... and properties ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example4/propA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example4/propB

...

Step 1

Create a file called 2005-10-31.rdf that contains a complete RDF/XML serialisation of the ontology, as at 2005-10-31 (or whatever the current date is). I.e. all resources defined by the ontology are described in this file, and this file represents a 'snapshot' or 'version' of the ontology.

Step 2

Create a file called 2005-10-31.html that contains HTML content documentation about all classes and properties defined by the ontology as at 2005-10-31 (or whatever the current date is). This document may include sections for each of the classes/properties documented, each section being headed by an HTML anchor whose name is identical to the fragment identifier of the documented class/property.

Step 3

Copy 2005-10-31.rdf and 2005-10-31.html to the directory /apachedocumentroot/VM/http-examples/example4-content/ on the server.

Step 4

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/ directory ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example4/$ example4-content/2005-10-31.html [R=303]

# Rewrite rule to serve directed HTML content from class/prop URIs
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example4/(.+) example4-content/2005-10-31.html#$1 [R=303,NE]

# Rewrite rule to serve RDF/XML content from the namespace URI by default
RewriteRule ^example4/ example4-content/2005-10-31.rdf [R=303]

(N.B. If a .htaccess file does not exist, create one.)

Result

This configuration leads to the following interactions between client and server ...

Dereference the ontology URI, requesting HTML content

GET /VM/http-examples/example4/ HTTP/1.1
Host: isegserv.itd.rl.ac.uk
Accept: text/html

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example4-content/2005-10-31.html

(Redirect the client to current HTML documentation for the ontology.)

Dereference the URI of a class or property, requesting HTML content

GET /VM/http-examples/example4/ClassA HTTP/1.1
Host: isegserv.itd.rl.ac.uk
Accept: text/html

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example4-content/2005-10-31.html#ClassA

(Redirect the client to the fragment of current HTML documentation for the ontology relevant to the class or property.)

Dereference the ontology URI, default case

GET /VM/http-examples/example4/ HTTP/1.1
Host: isegserv.itd.rl.ac.uk

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example4-content/2005-10-31.rdf

(Redirect the client to the current RDF description of the ontology.)

Dereference the URI of a class or property, default case

GET /VM/http-examples/example4/ClassA HTTP/1.1
Host: isegserv.itd.rl.ac.uk

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example4-content/2005-10-31.rdf

(Redirect the client to the current RDF description of the ontology.)

Notes

For this configuration to work, the directory option 'MultiViews' must be disabled, and a directory called /apachedocumentroot/VM/http-example/example4/ must not actually exist on the server's file system.

Recipe 5. Slash Configuration, Extended, Multiple HTML Documents

This recipe gives an example configuration that satisfies the extended requirements for an ontology with a slash namespace.Both machine-readable (RDF) and human-readable (HTML) content is served at the namespace URI with the HTML documentation being given as several hyperlinked HTML documents plus an overview document.

For ontology ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example5/

... defining classes ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example5/ClassA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example5/ClassB

... and properties ...

http://isegserv.itd.rl.ac.uk/VM/http-examples/example5/propA
http://isegserv.itd.rl.ac.uk/VM/http-examples/example5/propB

...

Step 1

Create a file called 2005-10-31.rdf that contains a complete RDF/XML serialisation of the ontology, as at 2005-10-31 (or whatever the current date is). I.e. all resources defined by the ontology are described in this file, and this file represents a 'snapshot' or 'version' of the ontology.

Step 2

Copy 2005-10-31.rdf to the directory /apachedocumentroot/VM/http-examples/example5-content/ on the server.

Step 3

Create files ClassA.html ClassB.html propA.html propB.html each of which contains HTML content documentation relevant to the class/property with the corresponding local name, as at 2005-10-31 (or whatever the current date is). Create a file index.html that contains HTML content documentation about the ontology itself, with hyperlinks to all class/property documentation.

Step 4

Copy ClassA.html ClassB.html propA.html propB.html and index.html to the directory /apachedocumentroot/VM/http-examples/example5-content/2005-10-31-docs/ on the server.

Step 5

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/ directory ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example5/$ example5-content/2005-10-31-docs/index.html [R=303]

# Rewrite rule to serve HTML content from class or prop URIs if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example5/(.+) example5-content/2005-10-31-docs/$1.html [R=303]

# Rewrite rule to serve RDF/XML content from the namespace URI by default
RewriteRule ^example5/ example5-content/2005-10-31.rdf [R=303]

(N.B. If a .htaccess file does not exist, create one.)

Result

This configuration leads to the following interactions between client and server ...

Dereference the ontology URI, requesting HTML content

GET /VM/http-examples/example5/ HTTP/1.1
Host: isegserv.itd.rl.ac.uk
Accept: text/html

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example5-content/2005-10-31-docs/index.html

(Redirect the client to current HTML overview documentation for the ontology.)

Dereference the URI of a class or property, requesting HTML content

GET /VM/http-examples/example5/ClassA HTTP/1.1
Host: isegserv.itd.rl.ac.uk
Accept: text/html

HTTP/1.x 303 See Other
Location: http://isegserv.itd.rl.ac.uk/VM/http-examples/example5-content/2005-10-31-docs/ClassA.html

(Redirect the client to current HTML documentation for the class or property.)

Dereference the ontology URI, default case

Same as example 4.

(Redirect the client to the current RDF description of the ontology.)

Dereference the URI of a class or property, default case

Same as example 4.

(Redirect the client to the current RDF description of the ontology.)

Notes

If you have the directory options Indexes and MultiViews enabled for the directory /apachedocumentroot/VM/http-examples/example5-content/2005-10-31-docs/ then you can replace the first two rewrite rules with one single rewrite rule ...

RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example5/(.*) example5-content/2005-10-31-docs/$1 [R=303]

This configuration is particularly suited to the use of documentation generated by the OWLDoc plugin for Protege [@@TODOREF].

A Note on PURLs

PURLs ('Persistent URLs') are URIs from the http://purl.org/ URI space. Because it is not possible for a user of this service to configure the PURL server directly other than to specify the redirect URL for each PURL, server configuration for ontologies with http://purl.org/ namespaces differs from other cases, and these are treated in separate recipes.

Note also that PURL servers use a 302 redirect code, and therefore ontologies with slash namespaces using PURL servers will not strictly conform with the TAG resolution on httpRange-14.

Recipe 6. PURL Hash Configuration, Minimal

This recipe gives an example configuration that satisfies the minimum requirements for an ontology with a hash namespace within the http://purl.org/ URI space. Only machine-readable (RDF) content is served at the namespace URI.

For ontology ...

http://purl.org/net/swbp-vm/example6#

... defining classes ...

http://purl.org/net/swbp-vm/example6#ClassA
http://purl.org/net/swbp-vm/example6#ClassB

... and properties ...

http://purl.org/net/swbp-vm/example6#propA
http://purl.org/net/swbp-vm/example6#propB

...

Step 1

Create a file called example6.rdf that contains a complete RDF/XML serialisation of the ontology. I.e. all resources defined by the ontology are described in this file.

Step 2

Copy example6.rdf to the directory /apachedocumentroot/VM/http-examples/ on the server from which you wish to serve the content (in this example the server is isegserv.itd.rl.ac.uk).

Step 3

Setup the following PURL ...

PURL: http://purl.org/net/swbp-vm/example6 
URL:  http://isegserv.itd.rl.ac.uk/VM/http-examples/example6.rdf 

Notes

If the server is already configured to serve files with the .rdf extension as content-type application/rdf+xml then you don't have to do anything further. If this is not the case, you will need to add the directive ...

AddType application/rdf+xml .rdf

... either to the main apache configuration files, or if you don't have access to these, to the per-directory configuration file (.htaccess) for the directory /apachedocumentroot/VM/http-examples/ on the server.

Recipe 7. PURL Slash Configuration, Minimal

This recipe gives an example configuration that satisfies the minimum requirements for an ontology with a slash namespace within the http://purl.org/ URI space. Only machine-readable (RDF) content is served at the namespace URI.

N.B. this example does not strictly conform with the TAG resolution on httpRange-14 because the purl.org servers use a 302 redirect code, and not a 303.

For ontology ...

http://purl.org/net/swbp-vm/ex7/

... defining classes ...

http://purl.org/net/swbp-vm/ex7/ClassA
http://purl.org/net/swbp-vm/ex7/ClassB

... and properties ...

http://purl.org/net/swbp-vm/ex7/propA
http://purl.org/net/swbp-vm/ex7/propB

...

Step 1

Create a file called ex7.rdf that contains a complete RDF/XML serialisation of the ontology. I.e. all resources defined by the ontology are described in this file.

Step 2

Copy ex7.rdf to the directory /apachedocumentroot/VM/http-examples/ on the server from which you wish to serve the content (in this example the server is isegserv.itd.rl.ac.uk).

Step 3

Setup the following Partial Redirect PURL ...

PR PURL: http://purl.org/net/swbp-vm/ex7/ 
Root URL:  http://isegserv.itd.rl.ac.uk/VM/http-examples/ex7/ 

Step 4

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/directory on the server ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to serve RDF/XML content from all partially redirected URIs
RewriteRule ^ex7/ ex7.rdf

(N.B. If a .htaccess file does not exist, create one.)

Notes

In the above recipe the single rewrite rule is an internal redirect. This minimises the number of external (i.e HTTP) redirects involved in the dereference action. However, you could also implement this rewrite rule as an external redirect, by replacing the above rule with ...

# Rewrite rule to serve RDF/XML content from all partially redirected URIs
RewriteRule ^ex7/ ex7.rdf [R=303]

... this creates an additional HTTP redirect in the dereference action, but possibly makes it clearer to the client that attempts to dereference ontology, class or property URIs all end up at the same place.

It is also possible to avoid any server configuration by creating individual PURLs for each class and property of the ontology, all referencing the same URL (rather than a Partial Redirect PURL). However, if you changed the content location, you'd have to update each PURL, which is cumbersome and impractical for medium- to large- size ontologies.

Recipe 8. PURL Hash Configuration, Extended

This recipe gives an example configuration that satisfies the extended requirements for an ontology with a hash namespace within the http://purl.org/ URI space. Both machine-readable (RDF) and human-readable (HTML) content is served at the namespace URI.

For ontology ...

http://purl.org/net/swbp-vm/example8#

... defining classes ...

http://purl.org/net/swbp-vm/example8#ClassA
http://purl.org/net/swbp-vm/example8#ClassB

... and properties ...

http://purl.org/net/swbp-vm/example8#propA
http://purl.org/net/swbp-vm/example8#propB

...

Step 1

Create a file called 2005-10-31.rdf that contains a complete RDF/XML serialisation of the ontology, as at 2005-10-31 (or whatever the current date is). I.e. all resources defined by the ontology are described in this file, and this file represents a 'snapshot' or 'version' of the ontology.

Step 2

Create a file called 2005-10-31.html that contains HTML content documentation about all classes and properties defined by the ontology as at 2005-10-31 (or whatever the current date is). This document may include sections for each of the classes/properties documented, each section being headed by an HTML anchor whose name is identical to the fragment identifier of the documented class/property.

Step 3

Copy 2005-10-31.rdf and 2005-10-31.html to the directory /apachedocumentroot/VM/http-examples/example8-content/ on the server from which you wish to serve the content (in this example the server is isegserv.itd.rl.ac.uk).

Step 4

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/ directory ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to make sure we serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^example8$ example8-content/2005-10-31.html [R=303]

# Rewrite rule to make sure we serve the RDF/XML content from the namespace URI by default 
RewriteRule ^example8$ example8-content/2005-10-31.rdf [R=303]

Step 5

Setup the following PURL ...

PURL: http://purl.org/net/swbp-vm/example8 
URL:  http://isegserv.itd.rl.ac.uk/VM/http-examples/example8

Notes

Because we can't configure the PURL server for content-negotiation, this example configures the content server to perform negotiation after the 302 redirect from the PURL server.

@@TODO It is technically possible to content negotiate without performing additional redirects, via a type-map or via built-in Apache content negotiation - is this ok? In this case there would not be separate URIs for RDF and HTML content.

Recipe 9. PURL Slash Configuration, Extended, Single HTML Document

This recipe gives an example configuration that satisfies the extended requirements for an ontology with a slash namespace within the http://purl.org/ URI space. Both machine-readable (RDF) and human-readable (HTML) content is served at the namespace URI. The HTML documentation is served as a single file.

N.B. this example does not strictly conform with the TAG resolution on httpRange-14 because the purl.org servers use a 302 redirect code, and not a 303.

For ontology ...

http://purl.org/net/swbp-vm/ex9/

... defining classes ...

http://purl.org/net/swbp-vm/ex9/ClassA
http://purl.org/net/swbp-vm/ex9/ClassB

... and properties ...

http://purl.org/net/swbp-vm/ex9/propA
http://purl.org/net/swbp-vm/ex9/propB

...

Step 1

Create a file called 2005-10-31.rdf that contains a complete RDF/XML serialisation of the ontology, as at 2005-10-31 (or whatever the current date is). I.e. all resources defined by the ontology are described in this file, and this file represents a 'snapshot' or 'version' of the ontology.

Step 2

Create a file called 2005-10-31.html that contains HTML content documentation about all classes and properties defined by the ontology as at 2005-10-31 (or whatever the current date is). This document may include sections for each of the classes/properties documented, each section being headed by an HTML anchor whose name is identical to the fragment identifier of the documented class/property.

Step 3

Copy 2005-10-31.rdf and 2005-10-31.html to the directory /apachedocumentroot/VM/http-examples/ex9-content/ on the server from which you wish to serve the content (in this example the server is isegserv.itd.rl.ac.uk)..

Step 4

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/ directory ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^ex9/$ ex9-content/2005-10-31.html [R=303]

# Rewrite rule to serve directed HTML content from class/prop URIs
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^ex9/(.+) ex9-content/2005-10-31.html#$1 [R=303,NE]

# Rewrite rule to serve RDF/XML content from the namespace URI by default
RewriteRule ^ex9/ ex9-content/2005-10-31.rdf [R=303]

(N.B. If a .htaccess file does not exist, create one.)

Step 5

Setup the following Partial Redirect PURL ...

PR PURL: http://purl.oclc.org/net/swbp-vm/ex9/ 
URL Root:  http://isegserv.itd.rl.ac.uk/VM/http-examples/ex9/

Notes

This configuration could be cumbersome to maintain, because every single PURL has to be updated when you publish a new version of the ontology.

This configuration would be the most appropriate for Dublin Core Metadata Terms.

Recipe 10. PURL Slash Configuration, Extended, Multiple HTML Documents

This recipe gives an example configuration that satisfies the extended requirements for an ontology with a slash namespace within the http://purl.org/ URI space. Both machine-readable (RDF) and human-readable (HTML) content is served at the namespace URI with the HTML documentation being given as several hyperlinked HTML documents plus an overview document.

N.B. this example does not strictly conform with the TAG resolution on httpRange-14 because the purl.org servers use a 302 redirect code, and not a 303.

For ontology ...

http://purl.org/net/swbp-vm/ex10/

... defining classes ...

http://purl.org/net/swbp-vm/ex10/ClassA
http://purl.org/net/swbp-vm/ex10/ClassB

... and properties ...

http://purl.org/net/swbp-vm/ex10/propA
http://purl.org/net/swbp-vm/ex10/propB

...

Step 1

Create a file called 2005-10-31.rdf that contains a complete RDF/XML serialisation of the ontology, as at 2005-10-31 (or whatever the current date is). I.e. all resources defined by the ontology are described in this file, and this file represents a 'snapshot' or 'version' of the ontology.

Step 2

Copy 2005-10-31.rdf to the directory /apachedocumentroot/VM/http-examples/ex10-content/ on the server from which you wish to serve the content (in this example the server is isegserv.itd.rl.ac.uk).

Step 3

Create files ClassA.html ClassB.html propA.html propB.html each of which contains HTML content documentation relevant to the class/property with the corresponding local name, as at 2005-10-31 (or whatever the current date is). Create a file index.html that contains HTML content documentation about the ontology itself, with hyperlinks to all class/property documentation.

Step 4

Copy ClassA.html ClassB.html propA.html propB.html and index.html to the directory /apachedocumentroot/VM/http-examples/ex10-content/2005-10-31-docs/ on the server from which you wish to serve the content (in this example the server is isegserv.itd.rl.ac.uk).

Step 5

Add the following directives to the .htaccess file in the /apachedocumentroot/VM/http-examples/ directory ...

# Turn off MultiViews
Options -MultiViews

# Directive to ensure *.rdf files served as appropriate content type, 
# if not present in main apache config
AddType application/rdf+xml .rdf

# Rewrite engine setup
RewriteEngine On
RewriteBase /VM/http-examples

# Rewrite rule to serve HTML content from the namespace URI if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^ex10/$ ex10-content/2005-10-31-docs/index.html [R=303]

# Rewrite rule to serve HTML content from class or prop URIs if requested
RewriteCond %{HTTP_ACCEPT} text/html [OR]
RewriteCond %{HTTP_ACCEPT} text/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xml [OR]
RewriteCond %{HTTP_ACCEPT} application/xhtml+xml
RewriteRule ^ex10/(.+) ex10-content/2005-10-31-docs/$1.html [R=303]

# Rewrite rule to serve RDF/XML content from the namespace URI by default
RewriteRule ^ex10/ ex10-content/2005-10-31.rdf [R=303]

(N.B. If a .htaccess file does not exist, create one.)

Step 6

Setup the following Partial Redirect PURLs ...

PR PURL: http://purl.org/net/swbp-vm/ex10/ 
Root URL:  http://isegserv.itd.rl.ac.uk/VM/http-examples/ex10/

Notes

@@TODO

Requirements

This section describes requirements for HTTP behaviour of HTTP URIs denoting RDFS/OWL ontologies, classes and properties.

Minimum Requirements

M1. The 'authoritative' RDF description of an RDFS/OWL ontology, class or property denoted by an HTTP URI, can be obtained by dereferencing the URI of that ontology, class or property.

An HTTP client can obtain the 'authoritative' RDF description of an ontology, class, or property, by performing an HTTP GET request against the URI of that ontology, class or property. The RDF description is returned as an HTTP response whose content type is a registered MIME type for RDF content (currently only 'application/rdf+xml').

This is the default behaviour in the case that some form of content-negotiation has been implemented for these URIs. I.e. an HTTP GET request without an 'Accept:' header field will result in a response with content-type 'application/rdf+xml', which is a serialisation of a set of RDF statements, including those statements that constitute the 'authoritative' RDF description of the denoted resource.

N.B. it is reasonable for an attempt to dereference the URI of an RDF property or class to result in an RDF description of more than just that property or class.

M2. The behaviour of an HTTP URI denoting an RDFS/OWL ontology, class or property, does not lead to inconsistency in the interpretation of the nature of the denoted resource.

Currently the architecture of the web allows applications to draw inferences about the nature of a resource denoted by an HTTP URI, based on ...

(i) The HTTP response code obtained when dereferencing the URI [@@TODOREF TAG resolution httpRange-14].

... and ...

(ii) Where the URI contains a fragment identifier, the content-type(s) of the available representations [@@TODOREF???].

Given these constraints, for each HTTP URI denoting an RDFS/OWL ontology, class or property, the range of possible responses to HTTP requests against that URI will not lead applications to draw any inconsistent conclusions.

Extended Requirements

These requirements are an extension of the minimum requirements.

E1. 'Human-readable' documentation about an RDFS/OWL ontology, class or property, denoted by an HTTP URI, can be obtained by dereferencing the URI of that ontology, class or property.

An HTTP client such as a web browser can obtain 'human-readable' documentation relating to an RDFS/OWL ontology, class or property, by performing an HTTP GET request against the URI of that ontology, class or property, specifying 'Accept:' headers appropriate to the desired content-type in the request.

E2. Applications are able to differentiate between 'versions' (a.k.a. 'snapshots') of an ontology.

Given that an ontology changes over time, applications need a way to differentiate between 'versions' of the ontology.

Acknowledgments

The examples attempt to distill elements of good practice from currently deployed semantic web vocabularies/ontologies, especially the Dublin Core Metadata Terms, the Friend of a Friend Ontology, and the SKOS Core Vocabulary. All those who contributed to the development of these practices are gratefully acknowledged.

References

[@@TODO]

@@TODO.

APACHE

Apache Foundation HTTP Server Project
http://httpd.apache.org/

AWWW04

Architecture of the World Wide Web, Volume One, W3C Recommendation 15 December 2004
Available at http://www.w3.org/TR/2004/REC-webarch-20041215/

PURL

OCLC Persistent Uniform Resource Locator Service
http://www.purl.org/

RFC2616

IETF RFC 2616: Hypertext Transfer Protocol - HTTP/1.1, June 1999
http://www.ietf.org/rfc/rfc2616.txt

RFC3986

IETF RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, January 2005
http://www.ietf.org/rfc/rfc3986.txt

--- CVS Log ---

$Log: Overview.html,v $
Revision 1.17  2006/01/18 20:19:17  ajm65
Trivial change, to note that previous change 1.15->1.16 the log message is incorrect. This previous revision the actual change was to include interaction diagrams and tests for example 3, but not to actually change the config for examples 3,4 or 5 as is incorrectly stated in the log message. This was an error.

Revision 1.16  2006/01/18 19:38:59  ajm65
changed examples 3 4 and 5 to have HTML as the default response

Revision 1.15  2006/01/18 17:53:03  ajm65
Refactor recipes 1 and 2 to be more reader-friendly, by adding interaction diagrams at start and reworded initial text, and also by giving example messages as tests.

Revision 1.14  2006/01/16 19:05:40  ajm65
changed all client-server diagrams so text is embedded in this doc, and now use single background image

Revision 1.13  2006/01/10 17:33:23  ajm65
Added a 'result' section for first five recipes, describing the effect of that recipe (i.e. what it does).

Revision 1.12  2005/12/31 02:56:01  swick
Make title element match the title.  Fix a validation error.

Revision 1.11  2005/12/31 02:49:24  swick
Make sure all hash namespace URIs really do end with '#'.
Make all class names conform to the InitialCap convention.
Add lots of prose to abstract and introduction to give more motivation.
Expand the explaination of the hash/slash naming choices.

Revision 1.10  2005/11/28 15:35:45  ajm65
minor, fix typo in abstract

Revision 1.9  2005/11/22 17:19:33  ajm65
Redid all PURL slash examples to use partial redirect purls.

Revision 1.8  2005/11/21 19:06:04  ajm65
Fixed more typos.

Revision 1.7  2005/11/21 19:02:11  ajm65
Fixed some typos.

Revision 1.6  2005/11/21 18:57:52  ajm65
Completed first draft. (Requirements added.)

Revision 1.4  2005/11/21 15:08:12  ajm65
Fix CVS Id

Revision 1.3  2005/11/21 13:35:17  ajm65
Filled in up to recipe 4, skeleton for recipes 5-10 including PURL recipes.

Revision 1.2  2005/11/18 19:50:45  ajm65
Recipe 1 complete.  Other recipes TODO. Requirements TODO.

Revision 1.1  2005/11/18 18:16:09  ajm65
Initial, template only.


--- CVS Log ---