- Author: Mark A. Matienzo, Digital Public Library of America
- To: Technical Group of International Rights Statement Working Group
- CC: International Rights Statement Working Group
- Status: Personal views only
- View link: http://bit.ly/rs-http-behavior
- Public comment link: https://gist.github.com/anarchivist/16140cfa8c76008e384e
- For the sake of brevity, the shorthand
http://rs.int/is used for the full URI basehttp://rightsstatements.org/. - This document, when rendered properly, contains diagrams to represent HTTP interactions. If you do not see the diagrams, please use the view link provided.
- A rights statement URI is defined as the URI uniquely identifying the rights statement included in the SKOS concept scheme [RSSKOS] under development by the Technical Working Group.
- A human-readable representation is understood to refer to a representation to be presented to a person, e.g. an HTML page rendered in a web browser.
- A human-readable representation MAY have additional metadata passed to it as a "payload."
- A human-readable representation MAY also have a translation of the statement into a non-English language. Such a translation MUST be derived from a set of assertions with appropriate language tags in the canonical SKOS version [RSSKOS] of the rights statements.
- A representation URI is defined as the URI uniquely identifying a derived representation of a given rights statement.
- A machine-readable representation URI is understood to refer to a representation understood to be processed by an automated client.
- A human-readable representation URI is understood to refer to a representation to a human-readable representation.
This discussion originates in work from a joint DPLA/Europeana Rights Statements Working Group. For more background please read the Working Group's draft white papers on recommended statements [RSRECS] and technical infrastructure [RSTECH].
In the white paper on technical infrastructure [RSTECH], the proposed flow of HTTP requests follows the recommendations of Recipe 5, "Extended configuration for a 'slash namespace', using multiple HTML documents", of the Best Practice Recipes for Publishing RDF Vocabularies [SWBP-VOCAB-PUB], with an extension to support translations of rights statements. This memorandum addresses two needs identified during the discussion and revision process of the white paper on technical infrastructure [RSTECH]:
- The need to add additional metadata "payloads" to human-readable representations of the rights statements. This is informed by needs around two specific statements as identified by Europeana.
- The
OOC-NCstatement ("Out Of Copyright - NonCommercial Use Only") [RSTEXT] was created Public Domain works digitized in a public-private partnership. Within that partnership, the partners have agreed to limit commercial uses of this digital representation of the work by third parties. This statement needs an additional way to provide a contract expiry date that will allow the human-readable representation to the wordsuntil MM-DD-YYYYas part of the text displayed in the representation. - The
InC-OW-EUstatement ("In Copyright - EU Orphan Work") [RSTEXT] is designed for works identified as an orphan work in the country of first publication and in line with Directive 2012/28/EU [CELEX:32012L0028]. Since the beneficiary of the Directive is expected to have registered the work in the EU Orphan Works Database [EU-OW-DB], this statement needs an additional way to provide a link to the entry for the item in that database. - The proposed solution discussed by the technical working group suggested using a URI query parameter as part of the URI for the human-readable representation of rights statement, e.g.:
http://rs.int/page/OOC-NC/1.0/?date=2028-01-01
- The
- The need to refer to individual translations of a rights statements if desired. The proposed behavior in the white paper on technical infrastructure [RSTECH] describes a dereferencing behavior for translations based upon the transmission of an
Accept-Languageheader in the originating HTTP request. This makes it difficult to consistently refer the human-readable representation in linking from public user interfaces.
There was an initial proposal to use a implementation similar to that of the Creative Commons Metadata Scraper [CC-SCRAPER], which parses RDFa in HTML [HTML-RDFA] of a page identified using the Referer HTTP header [RFC7231] and creates a JSON response injected into deed pages.
The needs above and the proposed solutions raise the following issues:
- The rights statement URI and the representation URI do not identify the same thing. Adopters (meaning either aggregators or their content partners) expressing the rights statements in their metadata need a mechanism to consistently refer to the same rights statement of a given version, following best practices and standards of web architecture [RDF11-CONCEPTS, COOLURIS, WEBARCH].
- Specific guidance to adopters should be given about how to link to the appropriate resource if a specific human readable representation is desired. Without adequate guidance, this could lead to the confusion for adopters to associate the representation URI (e.g., one containing query parameters) to incorrectly as the rights statement URI.
- Both human and machine clients need an easy way to make requests that include additional information, such as desired content language or additional metadata for the specific rights statements listed above. There is a strong desire to be able to dereference a URI to retrieve a representation containing requested data. The Technical Working Group discussed issues with the CC Metadata Scraper [CC-SCRAPER], which range from performance to concerns to a lack of robustness when working in both HTTP and HTTPS environments.
- Both human and machine clients need adequate guidance to additional associated resources. The server hosting the statements needs to provide a reasonable set of behaviors that guide both kinds of clients to the appropriate resources. This is particularly true when links are used incorrectly, e.g. when a representation URI is used in place of the rights statement URI.
Fundamentally, this is a restatement of the recommendations in Best Practice Recipes for Publishing RDF Vocabularies [SWBP-VOCAB-PUB], and was identified as a recommendation by a commentator on the technical infrastructure white paper [RSTECH].
- Rights statement URIs should start with a specific prefix, e.g.
/vocab/or/id/:
http://rs.int/vocab/ic/1.0
- Machine-readable representation URIs should start with a different specific prefix, e.g.
/data/:
http://rs.int/data/ic/1.0
- Human-readable representation URIs should start with a different distinct prefix, e.g.
/page/:
http://rs.int/page/ic/1.0
Adopters should use rights statement URIs and representation URIs differently depending on needs and context
- When an adopter uses the URI in metadata (e.g. in a set of RDF statements about an item), the URI associated with the rights statement should be the rights statement URI, e.g.:
http://rs.int/vocab/OOC-NC/1.0
- Additional data for certain statements (i.e.
OOC-NCandIC-OW-EU) should be expressed in item metadata whenever possible (e.g. by using additional RDF statements). - Links to the human-readable representation URIs can be created dynamically, or stored separately, either for human or API consumption. For example, an aggregator can link to the following example URI for an
OOC-NCstatement with an expiration date in the Spanish version of their site:
http://rs.int/page/OOC-NC/1.0/es?&date=2028-01-01
- Full example to demonstrate how both additional statements in RDF metadata can express this additional information, along with a link to a human-readable representation:
<http://ex.org/providedCHO1234> <:rights> [
odrl:inheritFrom <http://rs.int/vocab/OOC-NC/1.0> ;
cc:deprecatedOn '2022-01-01' ;
ex:representation <http://rs.int/page/OOC-NC/1.0/?date=2028-01-01> .
] Responses to HTTP requests should provide additional guidance in headers about how to retrieve the proper resource depending on context
HTTP headers can provide appropriate guidance about how to access related resources. For example, headers returned when a client requests the representation URI can help them discover the associated rights statement URI.
When a client makes an invalid request, e.g. when requesting an RDF representation of a rights statement with an additional metadata payload, the server should respond accordingly. This is in part by design to ensure that the rights statement URIs are applied appropriately. The proposed response in this context is to return a response with an HTTP 406 Not Acceptable [RFC7231] status for invalid requests.
> GET http://rs.int/vocab/OOC-NC/1.0?date=2028-01-01
---
< 406 Not Acceptable
If a client requests a rights statement URI with query parameters containing an additional metadata payload, an Alternates header [RFC2295, RFC2296] can be returned with an HTTP 406 Not Acceptable [RFC7231] status. The Alternates header in this context functions as a means to provide guidance to a client when an unsuitable representation is requested.
> GET http://rs.int/vocab/OOC-NC/1.0?date=2028-01-01
---
< 406 Not Acceptable
< Alternates: {"/page/OOC-NC/1.0?date=2028-01-01" 0.9 {type text/html}}, {"/vocab/OOC-NC/1.0" 0.9}
The Content-Location header [RFC7231] is recommended to allow a generic machine-readable representation URI to refer to a specific machine-readable representation's URI, e.g.
> GET http://rs.int/data/ic/1.0
> Accept: text/turtle
---
< 200 OK
< Content-Location: http://rs.int/data/ic/1.0.ttl
The Link header [RFC5988] is recommended to provide additional link relations [LINK-RELATIONS] between representation URIs and rights statement URIs.
The describedby relation [LDP-LINK-RELATIONS] returned in a Link header for a request for a rights statement URI can assert that it is described by the associated readable representation URI, e.g.
> GET http://rs.int/vocab/und/1.0/
---
< 200 OK
< Link: <http://rs.int/page/und/1.0/>; rel=describedby
The derivedfrom relation [DRAFT-HOFFMAN-XML2RFC-21] in a Link header for a request for a representation URI can assert that the specified representation is derived from another representation. This may be useful to associate representations that are translations or have a specific metadata "payload."
> GET http://rs.int/page/OOC-NC/1.0/?date=2028-01-01
---
< 200 OK
< Link: <http://rs.int/page/OOC-NC/1.0/>; rel=derivedfrom
The following represents the proposed interactions between a client and the server hosting the rights statements and their representations.
This is as a revised interaction pattern from that included in the working group's technical white paper [RSTECH].
Note left of Client: req1:\n \nGET http://rightsstatements.org/vocab/1.0/\nAccept: text/html\nAccept-Language: es
Client->Server: req1
Note right of Server: rsp1:\n \n303 See Other\nLocation: http://rightsstatements.org/page/1.0/?language=es
Server-->Client: rsp1
Note left of Client: req2:\n \nGET http://rightsstatements.org/page/1.0/?language=es\nAccept: text/html\nAccept-Language: es
Client-Server: req2
Note right of Server: rsp2:\n \n200 OK\nContent-Language: es\nLink: <http://rs.int/page/1.0/>; rel=derivedfrom
Server-->Client: rsp2
This is as a revised interaction pattern from that included in the working group's technical white paper [RSTECH].
Note left of Client: req1:\n \nGET http://rightstatements.org/vocab/InC/1.0/\nAccept: text/html\nAccept-Language: es
Client->Server: req1
Note right of Server: rsp1:\n \n303 See Other\nLocation: http://rightstatements.org/page/InC/1.0/?language=es
Server-->Client: rsp1
Note left of Client: req2:\n \nGET http://rightstatements.org/page/InC/1.0/?language=es\nAccept: text/html\nAccept-Language: es
Client-Server: req2
Note right of Server: rsp2:\n \n200 OK\nContent-Language: es\nLink: <http://rightstatements.org/page/InC/1.0/>; rel=derivedfrom
Server-->Client: rsp2
Note left of Client: req1:\n \nGET http://rightstatements.org/vocab/InC/1.0/\nAccept: text/turtle
Client->Server: req1
Note right of Server: rsp1:\n \n303 See Other\nLocation: http://rightstatements.org/data/InC/1.0/
Server-->Client: rsp1
Note left of Client: req2:\n \nGET http://rightstatements.org/data/InC/1.0/\nAccept: text/turtle
Client-Server: req2
Note right of Server: rsp2:\n \n200 OK\nContent-Type: text/turtle\nContent-Location: http://rightstatements.org/data/InC/1.0.ttl\nLink: <http://rightstatements.org/page/InC/1.0/>; rel=derivedfrom
Server-->Client: rsp2
Note left of Client: req1:\n \nGET http://rightstatements.org/page/OOC-NC/1.0/?date=2028-01-01
Client->Server: req1
Note right of Server: rsp1:\n \n200 OK\nLink: <http://rightstatements.org/page/OOC-NC/1.0/>;\n rel=derivedfrom\nContent-Type: text/html; charset=utf-8\n \n<!DOCTYPE html>\n\n<!-- skip -->\n...This expires on 01 January 2028 ...
Server-->Client: rsp1
Note left of Client: req1:\n \nGET http://rightstatements.org/vocab/OOC-NC/1.0/?date=2028-01-01\nAccept: text/html
Client->Server: req1
Note right of Server: rsp1:\n \n406 Not Acceptable\nAlternates: {"/page/OOC-NC/1.0/?date=2028-01-01" 0.9 {type text/html}},\n{"/vocab/OOC-NC/1.0/" 0.9}
Server-->Client: rsp1
Note left of Client: req2:\n \nGET http://rightstatements.org/page/OOC-NC/1.0/?date=2028-01-01
Client-Server: req2
Note right of Server: rsp2:\n \n200 OK\nLink: <http://rightstatements.org/page/OOC-NC/1.0/>; rel=derivedfrom\nContent-Type: text/html; charset=utf-8\n \n<!DOCTYPE html>\n\n<!-- skip -->\n...This expires on 01 January 2028 ...
Server-->Client: rsp2
Note left of Client: req1:\n \nGET http://rightstatements.org/vocab/OOC-NC/1.0/?date=2028-01-01\nAccept: text/turtle
Client->Server: req1
Note right of Server: rsp1:\n \n406 Not Acceptable\nAlternates: {"/page/OOC-NC/1.0/?date=2028-01-01" 0.9 {type text/html}},\n{"/data/OOC-NC/1.0/" 0.9 {type text/turtle}}
Server-->Client: rsp1
Note left of Client: req2:\n \nGET http://rightstatements.org/data/OOC-NC/1.0/\nAccept: text/turtle
Client->Server: req2
Note right of Server: rsp2:\n \n200 OK\nContent-Location: http://rightstatements.org/data/OOC-NC/1.0.ttl\nLink: <http://rightstatements.org/page/OOC-NC/1.0/>; rel=derivedfrom
Server-->Client: rsp2
Note left of Client: req1:\n \nGET http://rightstatements.org/page/InC/1.0/?date=2028-01-01\nAccept: text/html
Client->Server: req1
Note right of Server: rsp1:\n \n406 Not Acceptable\nAlternates: {"/page/InC/1.0/" 0.9 {type text/html}},\n{"/data/InC/1.0/" 0.9 {type text/turtle}}
Server-->Client: rsp1
Note left of Client: req2:\n \nGET http://rightstatements.org/page/InC/1.0/\nAccept: text/html
Client->Server: req2
Note right of Server: rsp2:\n \n200 OK\nContent-Type: text/html
Server-->Client: rsp2
[CC-SCRAPER] Creative Commons. Deed Metadata Scraper.
[CELEX:32012L0028] European Parliament, Council of the European Union. Directive 2012/28/EU of the European Parliament and of the Council of 25 October 2012 on certain permitted uses of orphan works.
[COOLURIS] Leo Sauermann; Richard Cyganiak. Cool URIs for the Semantic Web. 3 December 2008. W3C Note.
[draft-hoffman-xml2rfc-21] P. Hoffman. The 'XML2RFC' version 3 Vocabulary. 6 July 2015. Internet-Draft.
[EU-OW-DB] Office for Harmonization in the Internal Market. Orphan Works Database.
[HTML-RDFA] Manu Sporny. HTML+RDFa 1.1 - Second Edition. 17 March 2015. W3C Recommendation.
[LINK-RELATIONS] Internet Assigned Numbers Authority. Link Relation Types.
[LDP-LINK-RELATIONS] Steve Speicher; John Arwe; Ashok Malhotra. "Link Relations." Linked Data Platform 1.0. 26 February 2015. W3C Recommendation.
[RDF11-CONCEPTS] Richard Cyganiak; David Wood; Markus Lanthaler. RDF 1.1 Concepts and Abstract Syntax. W3C Recommendation, 25 February 2014.
[RFC2295] K. Holtman; A. Mutz. Transparent Content Negotiation in HTTP. March 1998. Experimental.
[RFC2296] K. Holtman; A. Mutz. HTTP Remote Variant Selection Algorithm -- RVSA/1.0. March 1998. Experimental.
[RFC5988] M. Nottingham. Web Linking. October 2010. Proposed Standard.
[RFC6892] E. Wilde. The 'describes' Link Relation Type. March 2013. Informational.
[RFC7231] R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. June 2014. Proposed Standard.
[RSRECS] International Rights Statements Working Group. Recommendations for Standardized International Rights Statements. May 2015.
[RSSKOS] International Rights Statements Working Group. RightsStatements.org data model. 15 July 2015.
[RSTECH] International Rights Statements Working Group. Recommendations for the Technical Infrastructure for Standardized International Rights Statements. May 2015.
[RSTEXT] Europeana/DPLA working group: detailed list of rights statements. July 2015.
[SWBP-VOCAB-PUB] Diego Berrueta; Jon Phipps. Best Practice Recipes for Publishing RDF Vocabularies. 28 August 2008. W3C Note.
[WEBARCH] Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. 15 December 2004. W3C Recommendation.

See comments in #projecthydra IRC logs, e.g.