ShareDoc:Content Negotiation

Content negotiation is the mechanism used for serving different representations of a resource mapped to a given URI to help the user agent (i.e. the requestor) specify which "shape" is best suited for it.

When a client wants to obtain a Share-VDE resource, it requests it via a URL. The server uses this URL and the corresponding metadata to choose one of the available variants. Each "variant" is called a representation and it is associated to a given format. The following table lists the supported formats.

Format	Description
JSON	https://en.wikipedia.org/wiki/HATEOAS
JSON-LD	https://json-ld.org/
RDF XML	https://www.w3.org/TR/rdf-syntax-grammar/
N-Triples	https://www.w3.org/TR/n-triples/
N3	https://www.w3.org/TeamSubmission/n3/
Turtle	https://www.w3.org/TR/turtle/
N-Quads	https://www.w3.org/TR/n-quads/
TriX	https://en.wikipedia.org/wiki/TriX_(serialization_format)
TriG	https://www.w3.org/TR/trig/
MARC	https://en.wikipedia.org/wiki/MARC_standards#MARC_formats
MARCXML	https://en.wikipedia.org/wiki/MARC_standards#MARCXML
RIS	https://en.wikipedia.org/wiki/RIS_(file_format)

RIS and MARC formats only: these media types are valid only at instance (e.g. /instances/I0003) or at bibliographic record level (e.g. /instances/I0003/records)

RDF formats only: some RDF format return graphs instead of a triple sets. In Share-VDE the fourth dimension (the graph URI) is used for associating a triple to its provenance. As a consequence of that, if the request asks for a format which provides "triples" level info, it will get a "merged" view of the triples coming from all provenances, without any indication about the provenance itself.

In the example below, the requested format is n-triples:

<https://svde.org/works/731631362144813> <http://id.loc.gov/ontologies/bibframe/expressionOf> <https://svde.org/opuses/401> .
<https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://id.loc.gov/ontologies/bibframe/Title> .
<https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014> <http://www.w3.org/2000/01/rdf-schema#label> "Alice's adventures in Wonderland" .
<https://svde.org/opuses/401> <http://id.loc.gov/ontologies/bibframe/title> <https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014> .
<https://svde.org/opuses/401> <http://www.loc.gov/mads/rdf/v1#authoritativeLabel> "Alice's adventures in Wonderland" .
<https://svde.org/opuses/401> <http://id.loc.gov/ontologies/bibframe/hasExpression> <https://svde.org/works/731631362144813> .
...

if instead the requestor asks for a format which includes also the 4th dimension, the resultset will contain the provenance information associated to each triple. See the same resource above using a TriX format:

<trix xmlns="http://www.w3.org/2004/03/trix/trix-1/">
  <graph>
    <uri>https://svde.org/agents/BL</uri>
    <triple>
      <uri>https://svde.org/works/731631362144813</uri>
      <uri>http://id.loc.gov/ontologies/bibframe/expressionOf</uri>
      <uri>https://svde.org/opuses/401</uri>
    </triple>
    <triple>
      <uri>https://svde.org/title_996/52f8c9bb-4545-3da1-82f9-e40e6f827014</uri>
      <uri>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</uri>
      <uri>http://id.loc.gov/ontologies/bibframe/Title</uri>
    </triple>
    ...
  </graph>
  <graph>
    <uri>https://svde.org/agents/UALBERTA</uri>
    <triple>
      <uri>https://svde.org/works/731631362144813</uri>
      <uri>http://id.loc.gov/ontologies/bibframe/expressionOf</uri>
      <uri>https://svde.org/opuses/401</uri>
    </triple>
    ...

There are three ways of negotiating the representation between the client and the server. The following sections describe them.

Path Extension

The idea of this approach is: each URL returns a given resource (note a collection is still a resource, although it is actually a set of resources); if the client wants to get back a given representation of that resource, it just needs to suffix the URL using one of the available extensions.

Examples:

• https://svde.org/opuses/401.json
• https://svde.org/opuses/401.rdf
• https://svde.org/opuses/401.ttl
• https://svde.org/opuses/401.nt
• https://svde.org/opuses/401.nq
• https://svde.org/opuses/401.trix
• https://svde.org/opuses.xml?q=opuses+whose+title+contains+alice

The following table lists the available extensions and the corresponding format.

Suffix	Format
.json	JSON (default)
.jsonld	JSON-LD
.rdf	RDF/XML
.xml	RDF/XML
.nt	N-Triples
.n3	Notation 3
.ttl	Turtle
.nq	N-Quads
.trix	TriX
.trig	TriG
.mrc	MARC (Binary)
.marcxml	MARCXML
.ris	RIS

Note: in case the requested suffix is not in the table above, the default format is JSON.

Request Parameter

The client can ask for a specific format by appending a "format" request parameter. The value of that parameter must be one of the suffixes listed in the previous paragraph (without the beginning .).

Examples:

• https://svde.org/opuses/401?format=json
• https://svde.org/opuses/401?format=rdf
• https://svde.org/opuses/401?format=ttl
• https://svde.org/opuses/401?format=nt
• https://svde.org/opuses/401?format=nq
• https://svde.org/opuses/401?format=trix
• https://svde.org/opuses.xml?format=json&q=opuses+whose+title+contains+alice

Note in case the request parameter contains an unknown format, a "406 Not Acceptable" error is returned.

The "Accept" Header

The Accept header lists the MIME types of media resources that the agent is willing to process. Although in the 99% of scenarios it consists of a single value (the requested media type), the accepted format is a comma-separated list of MIME types, each combined with a quality factor, that is a parameter indicating the relative degree of relevance between the specified MIME types.

Examples:

• */* (JSON will be chosen in this case)
• text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9

In case one value is indicated in the Accept header, if that is supported (see the table below) that format is returned, otherwise a "406 Not Acceptable" error is returned.

The following table lists the supported media types.

Suffix	Format
*/*	JSON (default)
application/json	JSON (default)
application/ld+json	JSON-LD
application/rdf+xml	RDF/XML
application/xml	RDF/XML
application/n-triples	N-Triples
text/rdf+n3	Notation 3
text/turtle	Turtle
application/n-quads	N-Quads
application/trix	TriX
application/trig	TriG
application/marc	MARC (Binary)
application/marcxml	MARCXML
application/x-research-info-systems	RIS