1. Introduction

The use of HTTP URIs to identify ORE Aggregations and Resource Maps leverages the extensive infrastructure and tools of the current World Wide Web [Web Architecture]. HTTP is the protocol best supported by web browsers, crawlers, search engines, feed aggregators, etc., and is thus the RECOMMENDED protocol and associated URI scheme for ORE Aggregations and Resource Maps.

An ORE Aggregation is a set of Aggregated Resources [Data Model] identified by a URI. An Aggregation is an abstract construct; its essential characteristics cannot be conveyed as a web document. Hence, no representation is available from the URI that identifies an Aggregation. However, the Aggregation URI provides a way to get a web document that describes the Aggregation: a Resource Map available from another URI. This document describes how make the link between Aggregation and Resource Map using HTTP and following the strategies of Cool URIs and the Linked Data Tutorial.

There may be one or more Resource Maps that describe a particular Aggregation. Multiple Resource Maps will likely differ in their serialization format and serialization specific metadata (e.g. creation time), and are thus separate web documents identified with different URIs (ReM-1, ReM-2, etc.).

In many application domains there are already many aggregations of resources on the web. These are often described by human-readable HTML pages, often called "Splash Pages", such as http://arxiv.org/abs/astro-ph/0601007 which provide description of an aggregation and access to its components. Typically, this approach does not provide a URI for the concept of the aggregation — the URI of the Splash Page is not the URI of the aggregation but rather of the HTML page. Nor does it provide a machine-readable description of the aggregation. ORE solves this problem by introducing a URI for the aggregation, and a standardized way to described the boundary of the aggregation by means of Resource Maps. Existing Splash Pages may accessed via the ORE Aggregationn URI. With RDFa it is even possible to embed a Resource Map in a Splash Page and this case is discussed below.

This document is divided into sections which describe different HTTP implementation scenarios. These scenarios differ in the server requirements needed to support them, and in the URI structure that results:

• Section 2 describes a clean and extensible implementation strategy requiring HTTP server support to implement 303 redirection and content negotiation. This is the RECOMMENDED strategy.
• Section 3 describes simpler use of 303 redirection for a single Resource Map.
• Section 4 describes a limited but very simple implementation strategy using hash URIs that requires no HTTP server support beyond the ability to serve files.
• Section 5 describes implementation with RFDa (or microformats) either alone or in addition to other formats.
• Section 6 gives the recommended behavior of HTTP Proxy URIs and details of the ORE Proxy URI resolver at http://oreproxy.org/r.

This document does not include guidance in the use of a generic resource (standing for a generic Resource Map) that supports content negotiation for different Resource Maps. These techniques are described in Cool URIs and may be used with ORE under certain conditions. Discussion will be included in an update to this document.

2. Implementation using 303 redirection and content negotiation

This implementation strategy is the most flexible and is RECOMMENDED in the following circumstances:

• Web server support for 303 redirection is available.
• Web server support for content negotiation is available.
• Support multiple Resource Maps is required.
• Desire to integrate Splash Pages into the solution (section 2.2).
• Desire to allow easy extensibility to additional Resource Maps and/or Splash Pages.

2.1 Multiple Resource Maps

Consider the case of two Resource Maps available to describe an Aggregation, perhaps an Atom serialization and an RDF/XML serialization. Each Resource Map MUST be available from a different URI (ReM-1 and ReM-2) but either SHOULD be accessible via the Aggregation URI (A-1). The server responds to a request for A-1 with a 303 See Other redirect to either ReM-1 or ReM-2 depending upon MIME-type preferences expressed in the request. An example HTTP interaction is shown in appendix C.2. The figure below illustrates this scenario in the case that the Atom Resource Map "wins" based on client preferences (or default server behavior if no preferences are given).

# Statements in ReM-1 (shown as red arrows)
ReM-1 ore:describes A-1.
A-1 ore:isDescribedBy ReM-2.   #discovery of ReM-2 from ReM-1

# Statements in ReM-2 (not shown in figure)
ReM-2 ore:describes A-1.
A-1 ore:isDescribedBy ReM-1.   #discovery of ReM-1 from ReM-2

The Aggregation and each Resource Map has a good URI. These URIs do not have to be related in the manner shown above although this is one logical and extensible arrangement. While the appropriate choice for a given system will likely be influenced by other considerations, it should not be forgotten that "good URIs do not change" [URI Style] and that extension is often required as systems evolve.

To aid in discovery of Resource Maps, it is RECOMMENDED that where there are multiple Resource Maps available for an Aggregation, the availability of other Resource Maps should be indicated using the ore:isDescribedBy predicate (statements shown above).

This scheme is easily extended by adding new Resource Maps (with URIs ReM-3 etc.) or to support an HTML Splash Page (section 2.2). It is an implementation decision as to which Resource Map is considered the default should no preference information be sent by the client, or if the preferred formats are not available. The most widely used serialization is likely the best choice and at present that is Atom.

2.2 Resource Maps and a Splash Page

If there is an HTML Splash Page (S-1) associated with an Aggregation then 303 redirection allows this to be accessed via the Aggregation alongside the Resource Maps. Thus human or machine readable information about the Aggregation is provided according to the client preference, following the recommendations of Cool URIs and the Linked Data Tutorial.

The figure below shows and Aggregation (A-1) with an HTML Splash Page (S-1) and two Resource Maps (ReM-1 and ReM-2).

# Statements in ReM-1 (shown as red arrows)
ReM-1 ore:describes A-1.
A-1 ore:isDescribedBy ReM-2.   #discovery of ReM-2 from ReM-1

# Statements in ReM-2 (not shown in figure)
ReM-2 ore:describes A-1.
A-1 ore:isDescribedBy ReM-1.   #discovery of ReM-1 from ReM-2

# In S-1 (shown as blue arrows)
<link rel="resourcemap" href="http://example.org/foo.atom" type="application/atom+xml" />
<link rel="resourcemap" href="http://example.org/foo.rdf" type="application/rdf+xml" />

The HTML Splash Page SHOULD include HTML <link> elements for discovery of the Resource Maps as shown in the figure, and MAY also include HTTP Link headers [Resource Map Discovery]. Additionally, each Resource Map SHOULD include ore:isDescribedBy predicates to allow discovery of other Resource Maps (statements shown above). It is an implementation choice as to whether the Splash Page is itself an Aggregated Resource within the Aggregation.

If a client expresses no MIME-type preference, the default redirection SHOULD be to a Resource Map and SHOULD NOT be to the Splash Page. Which Resource Map is provided by default is an implementation decision; the most widely used serialization available is likely the best choice.

2.3 Summary of recommended content negotiation behaviors

The specifications for content negotiation [RFC2295] provide considerable latitude for the server to select the "best variant". To promote interoperability between ORE clients and servers the following behaviors are RECOMMENDED. Example HTTP requests and responses are shown in appendix C.1

Recommended server behavior

The following rules allow 303 redirection with content negotiation to provide flexibility for advanced ORE clients. They also support use of Resource Maps by clients that do not supply preference (Accept) headers. In response to a request for an Aggregation URI:

• If the request includes an Accept header then try to honor the preference (including any Splash Page if HTML is requested). If the server cannot redirect to the requested format (or follow lower preferences) then redirect to a machine readable Resource Map (RDF/XML, Atom, RDFa)
• If the request does not include an Accept header then redirect to a machine readable Resource Map (e.g. RDF/XML, Atom, XHTML+RDFa).

Recommended client behavior

If servers follow the rules above, clients will receive a machine readable Resource Map in response to a request for an Aggregation URI without preference information.

• It is recommended that clients include an Accept header using standard MIME types (see appendix B) to specify their preference for human or machine readable data, and the specific format.

3. Implementation using 303 redirection without content negotiation

This implementation strategy is RECOMMENDED when:

• The is just one Resource Map for each Aggregation
• Web server support for content negotiation is not available

In either the simple case of an Aggregation described by just one Resource Map, or where content negotiation is not available for technical reasons, 303 redirection may be used without supporting content negotiation. Consider the following example Aggregation (A-1) which is described by one Resource Map (ReM-1):

The Aggregation, with URI A-1, is described by the Resource Map ReM-1. Access to A-1 SHOULD lead a user or agent to the Resource Map and this is done by HTTP redirection. The server responds to a request for A-1 with a 303 See Other redirect to ReM-1. An example HTTP interaction is shown in appendix C.2.

The URIs A-1 and ReM-1 do not have to be related in the manner shown above although this is one logical and extensible arrangement. While the appropriate choice for a given system will likely be influenced by other considerations, it should not be forgotten that "good URIs do not change" [URI Style] and that extension is often required as systems evolve.

This simple single Resource Map 303 redirection arrangement is easily extended to support additional Resource Maps and/or Splash Pages using 303 redirection with content negotiation (section 2). The URI patterns may be extended to support additional Resource Maps. To add and RDF/XML ReM-2 and a Splash Page S-1 one might use:

Aggregation:   A-1   = http://example.org/foo
Resource Map:  ReM-1 = http://example.org/foo.atom
               ReM-2 = http://example.org/foo.rdf
Splash Page:   S-1   = http://example.org/foo.html

Even without support for content negotiation, clients may be made aware of other Resource Maps by including ore:isDescribedBy predicates to link to other Resource Maps in each Resource Map, and by including HTML <link> headers in the Splash Page. While more limited than a full content negotiation solution, this arrangement fulfills the minimal requirement that access to the Aggregation leads a client to a Resource Map describing the Aggregation.

4. Simple implementation using hash URIs

This implementation strategy is RECOMMENDED when:

• The is just one Resource Map for each Aggregation
• Web server support for 303 redirection is not available

Without support from a web server one cannot use 303 redirection to arrange that an attempt to access the Aggregation leads to a Resource Map. A way around this limitation is to use hash URIs — the Aggregation URI is constructed by adding a fragment identifier to the Resource Map URI [RFC3986]. In the case of an Atom Resource Map the URIs might be:

# Statements in ReM-1 (shown as red arrow)
ReM-1 ore:describes A-1.

Resolution of fragment identifiers is a client-side behavior so any client seeing an HTTP URI with fragment identifier, say uri#fragment, will remove the #fragment and access uri. Only when a response is obtained might the client try to identify the correct fragment. In practice this means that either A-1 or ReM-1 above will yield the Resource Map at http://example.org/foo.atom. The use of a URI with fragment identifier to identify a real-world resource, such as the Aggregation, is discussed further in Cool URIs and the Linked Data Tutorial.

Use of a hash URI permits precise differentiation between the Resource Map and the Aggregation so that statements can be made about the appropriate resource. It also satisfies the requirement that a Resource Map can be obtained both via the Aggregation URI A-1 and directly from ReM-1. The very simple HTTP interaction in this case is shown in appendix C.3.

If there is an HTML Splash Page (S-1) associated with the Aggregation then that page SHOULD include an HTML <link> element to support discovery of the Resource Map as shown below, and MAY also include HTTP Link headers [Resource Map Discovery].

# Statements in ReM-1 (shown as red arrow)
ReM-1 ore:describes A-1.

# In S-1 (shown as blue arrow)
<link rel="alternate" href="http://example.org/foo.atom" type="application/atom+xml" />

4.1 Migration from hash URIs to support multiple Resource Maps

The use of a hash URIs for the Aggregation URI does not directly support the availability of multiple Resource Maps for a single Aggregation. Migration from this simple approach to more complex solution with multiple serializations can be accomplished in two ways described below. Both are imperfect compromises and implementers are cautioned to think about the possibility of later extension before selecting the hash URI approach.

1. Change URIs to adopt the 303 redirection strategy. There is no need to change the URI for original the Resource Map http://example.org/foo.atom. An additional Resource Map may be added at a new URI, say an RDF/XML Resource Map at http://example.org/foo.rdf, to give the following set of URIs:

   Aggregation:   A-1   = http://example.org/foo
   Resource Map:  ReM-1 = http://example.org/foo.atom
                  ReM-2 = http://example.org/foo.rdf
   

   With the new URI arrangement, clients attempting to access the old Aggregation URI http://example.org/foo.atom#aggregation would still find a Resource Map and a sufficiently smart client might be able to unravel the inconsistency that there is no description of the resource http://example.org/foo.atom#aggregation. However, the process may be made explicit by updating the Resource Maps to include a statement that http://example.org/foo.atom and http://example.org/foo.atom#aggregation identify the same resource:

   <http://example.org/foo>  owl:sameAs  <http://example.org/foo.atom#aggregation>.
   

2. Preserve existing URIs while adding other formats. If a new RDF/XML Resource Map were added at http://example.org/foo.rdf the set of URIs might be:

   Aggregation:   A-1   = http://example.org/foo.atom#aggregation
   Resource Map:  ReM-1 = http://example.org/foo.atom
                  ReM-2 = http://example.org/foo.rdf
   

   With this extension it is not possible to provide access to the multiple Resource Maps by content negotiation on A-1, or to change the default representation obtained via A-1. Each Resource Map would indicate the availability of other Resource Map(s) using the ore:isDescribedBy predicate, and a Splash Page would include HTML <link> elements to support discovery of the Resource Maps, and may also include HTTP Link headers.

5. Implementation with RDFa

RDFa provides means to include structured data, such as a Resource Map, within an XHTML page. A profile for the use of RDFa to serialize Resource Maps is given in Resource Map Implementation in RDFa. With embedded RDFa, an (X)HTML "Splash Page" may take on the dual role of a Resource Map serialization. A similar approach might be used with microformats.

Within the ORE Model, the URIs of all Resource Maps (ReM-1, ReM-2 etc.) MUST be distinct from the URI of the Aggregation (A-1). Similarly the URI of a Splash Page (S-1) MUST be distinct from the URI of the Aggregation. The use of RDFa with 303 redirection is described in section 5.1, and the use of RDFa with hash URIs in section 5.2.

5.1 RDFa with 303 redirection

In the case of a 303 redirection implementation, the (X)HTML page containing the RDFa may be treated in the same way as a Resource Map in any other format. If the XHTML page contains the only Resource Map serialization for the Aggregation then one might have URIs:

Aggregation:   A-1   = http://example.org/foo
Resource Map:  ReM-1 = http://example.org/foo.html      (includes RDFa Resource Map)

where the server responds to a request for A-1 with a 303 redirection to ReM-1 as described in section 3.

If there are multiple serializations then the default 303 redirect should be to the XHTML page. This not only fulfills the requirement of default redirection to a machine readable Resource Map, but will ensure that a web browser receives the most helpful version of the Resource Map — the one embedded in a human readable XHTML page. If preference information is supplied with the HTTP request, the server may use content negotiation to serve the most appropriate Resource Map. If Resource Maps were available in XHTML/RDFa and Atom then URIs might be:

# Statements in ReM-1 == S-1 (shown as red arrows)
ReM-1 ore:describes A-1.
A-1 ore:isDescribedBy ReM-2.   #discovery of ReM-2 from ReM-1

This schemes is easily extended to additional Resource Maps by simply adding new Resource Maps with URI ReM-3, say http://example.org/foo.rdf for RDF/XML, etc..

5.2 RDFa with hash URIs

In case of a simple implementation using hash URIs, the XHTML page containing the RDFa Resource Map serialization must have the Aggregation URI A-1:

Aggregation:   A-1   = http://example.org/foo.html#aggregation
Resource Map:  ReM-1 = http://example.org/foo.html

The RDFa data must be written so that the URIs above are used in statements. The Aggregation URI is http://example.org/foo.html#aggregation and not the page URI http://example.org/foo.html. This is described in detail in the RDFa User Guide [ RDFa Resource Maps].

6. Proxy URIs

The ORE Model [Data Model] introduces Proxy URIs which establish Aggregation-specific identities for Aggregated Resources. From a modelling perspective, Proxy URIs need only be unique to a specific Aggregation and to a specific Aggregated Resource, and have these connections indicated with the appropriate predicates (ore:proxyIn, ore:proxyFor). All authoritative Resource Maps that describe the same Aggregation MUST express the same Proxy URIs for the Aggregated Resources ([Data Model section 3.3). When implemented using HTTP, Proxy URIs SHOULD satisfy the additional requirements given below so that clients dereferencing a Proxy URI will be redirected to the Aggregated Resource while also being informed of the Aggregation context. Conveying this information in responses requires server support.

The ORE Proxy URI resolver provides a way to implement Proxy URIs without the need for local server support or any registration. Proxy URIs are constructed as queries to the resolver which contain both the target Aggregated Resource URI and Aggregation context URI.

6.1 Requirements for HTTP Proxy URIs

Proxy URIs MUST be unique to a specific Aggregation (A-1) and to a specific Aggregated Resource (AR-1). They are thus able to "stand for" the Aggregated Resource in the context of the particular Aggregation. If an HTTP Proxy URI is used as a reference to an Aggregated Resources in the context of an Aggregation then it is desirable that dereferencing it with a standard web browser will return the Aggregated Resource itself (say a JPEG image or PDF document). In addition, dereference of the Proxy URI by an ORE aware client or agent should reveal the Aggregation context. In order to meet these two requirements, when dereferenced HTTP Proxy URIs MUST:

1. Redirect the client to the Aggregated Resource with HTTP status code "303 See Other" (other 3xx status codes do not have the correct semantics) and a Location header:

   Location: AR-1
   

2. Indicate the Aggregation context in the HTTP response with the HTTP Link header which is typed with the aggregation relation:

   Link: <A-1>; rel="aggregation"
   

The ORE Proxy URI resolver is one implementation that meets these requirements. The particular syntax described below could be reused for other Proxy URI resolvers with different base URIs. With this or other syntaxes, implementers should note the URI encoding issues mentioned below.

6.2 ORE Proxy URI resolver at http://oreproxy.org/r

The ORE Proxy URI resolver at http://oreproxy.org/r is provided as a service to the community. Use of the http://oreproxy.org/r resolver requires only that Proxy URIs are constructed by following the syntax rules described here. There is no need to register new Proxy URIs or Resource Maps or Aggregations because all of the information needed to implement the Proxy URI requirements given above is included in the Proxy URI itself. Namely, the URIs of the Aggregated Resource AR-1 and the Aggregation A-1 context. The syntax for the Proxy URI is:

http://oreproxy.org/r?what=AR-1&where=A-1

and an example might be

http://oreproxy.org/r?what=http://example.org/aggregated_resource_456&where=http://example.org/aggregation_123

Proxy URIs are constructed according to the following rules:

• The parameters what and where MUST be given in the order shown.

• The URIs of the Aggregated Resource AR-1 and of the Aggregation A-1 MUST be appropriately URI encoded as parts of the query component of the Proxy URI. All except the following characters should be percent encoded in A-1 and AR-1 when used in the Proxy URI (see URI syntax specification [RFC3986]):

  query-non-escaped = ALPHA / DIGIT / "-" / "." / "_" / "~" / ":" / "@" / "/" / "?"
  

  Note that this means that there MUST be double-escaping of any % characters that are already used to indicated percent encoded characters in A-1 or AR-1. For example, if AR-1=http://example.org/aggregated%26resource and A-1=http://example.org/aggregation_123, the % in %26 must be encoded as %25, giving:

  http://oreproxy.org/r?what=http://example.org/aggregated%2526resource&where=http://example.org/aggregation_123
  

  Note also that it is essential that the # character be correctly escaped (as %23) if either A-1 or AR-1 contain a fragment identifier component. If not, a browser would interpret the # character as the end of the query string and not sent the rest of the Proxy URI to the resolver.

• The scheme and host components SHOULD be specified in normalized (lowercase) form.

All applications except the application creating the Proxy URI and the resolver SHOULD treat the Proxy URI as opaque. The rules for parameter order, uniform escaping and normalization mean that the same Proxy URI will be constructed by different applications for the same AR-1 and A-1, and thus the Proxy URIs will be understood to identify the same resource by URI comparison.

When a client dereferences a http://oreproxy.org/r Proxy URI it will be redirected to the Aggregated Resource A-1 and the Aggregation context will be indicated in an HTTP Link header as described in the Proxy URI requirements above. Clients that cannot or do not interpret the Link header, such as an ordinary web browser, will silently be redirected to the Aggregated Resource. ORE aware clients will be able to deduce the Aggregation context.

7. Trust and Authority

Notions of trust are notoriously complex, hard to establish, and yet essential for many applications. The ORE specifications are based on Web and Semantic Web standards which provide authority rules as a scaffolding to allow applications to establish trust. In particular, the ORE Model uses RDF which allows anyone to say anything about anything although understanding who or what is doing the saying may help one establish trust (or not). This section outlines elements of authority determination based on the Aggregation and Resource Map URIs.

7.1 Authoritative Description

Imagine being given the URI of an Aggregation. How can one find an authoritative Resource Map describing that aggregation? The Web Architecture depends upon the URI owner to provide authoritative descriptions of the resource identified by the URI (see URI allocation in [Web Architecture], [Linked Data Tutorial]). The ORE specifications follow this notion. It is expected that an attempt to dereference the URI of an Aggregation will lead (via one of the mechanisms described above) to an authoritative Resource Map. A Resource Map obtained via the Aggregation URI is thus considered an authoritative description of the Aggregation [ORE Data Model].

Note that even an authoritative Resource Map may contain statements that are not authoritative in other senses. For example, an Aggregated Resource may be described as being a JPEG image but dereference of the Aggregated Resource might lead to an authoritative representation and HTTP metadata for a PDF document.

8. References

[Atom Resource Maps]

ORE Specification - Representing Resource Maps Using the Atom Syndication Format, Carl Lagoze, Herbert Van de Sompel, Pete Johnston, Michael Nelson, Robert Sanderson, Simeon Warner (editors), 2008-10-17. Available at http://www.openarchives.org/ore/1.0/atom

[Cool URIs]

Cool URIs for the Semantic Web Leo Sauermann, Richard Cyganiak, Danny Ayers, Max Völkel, 2008-03-31. Available at http://www.w3.org/TR/2008/NOTE-cooluris-20080331/ and latest version at http://www.w3.org/TR/cooluris/

[Data Model]

ORE Specification - Abstract Data Model, Carl Lagoze, Herbert Van de Sompel, Pete Johnston, Michael Nelson, Robert Sanderson, Simeon Warner (editors), 2008-10-17. Available at http://www.openarchives.org/ore/1.0/datamodel

[IANA MIME]

IANA MIME Media Types, Accessed 2008-10-06. Available at http://www.iana.org/assignments/media-types/

[Linked Data Tutorial]

How to Publish Linked Data on the Web, Chris Bizer, Richard Cyganiak, Tom Heath, 2007-07-27. Available at http://www4.wiwiss.fu-ber\lin.de/bizer/pub/LinkedDataTutorial/20070727/ . Latest version available at http://www4.wiwiss.fu-berlin.de/bizer/pub/LinkedDataTutorial/

[Resource Map Discovery]

ORE Specification - Resource Map Discovery, Carl Lagoze, Herbert Van de Sompel, Pete Johnston, Michael Nelson, Robert Sanderson, Simeon Warner (editors), 2008-10-17. Available at http://www.openarchives.org/ore/1.0/discovery

[RFC2295]

IETF RFC 2295: Transparent Content Negotiation, K. Holtman, A. Mutz, 1998-03. Available at http://www.ietf.org/rfc/rfc2295.txt

[RFC2616]

IETF RFC 2616: Hypertext Transfer Protocol - HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, June 1999. Available at http://www.ietf.org/rfc/rfc2616.txt

[RFC3986]

IETF RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter. Available at http://www.ietf.org/rfc/rfc3986.txt

[RDFa]

RDFa in XHTML: Syntax and Processing. A collection of attributes and processing rules for extending XHTML to support RDF, Ben Adida, Mark Birbeck, Shanne McCarron and Steven Pemberton (editors). W3C Working Draft, 2007-10-18. Available at http://www.w3.org/TR/2007/WD-rdfa-syntax-20071018/ and latest version available at http://www.w3.org/TR/rdfa-syntax/

[RDFa Resource Maps]

ORE User Guide - Resource Map Implementation in RDFa, Carl Lagoze, Herbert Van de Sompel, Pete Johnston, Michael Nelson, Robert Sanderson, Simeon Warner (editors), 2008-10-17. Available at http://www.openarchives.org/ore/1.0/rdfa

[URI Style]

Cool URIs don't change, Tim Berners-Lee, 1998. Available at http://www.w3.org/Provider/Style/URI

[Web Architecture]

Architecture of the World Wide Web, Volume One, I. Jacobs and N. Walsh, Editors, World Wide Web Consortium, 15 January 2004. Available at http://www.w3.org/TR/webarch/

[XHTML Media Types]

XHTML Media Types, Ishikawa Masayasu, 2002. Available at http://www.w3.org/TR/xhtml-media-types