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.
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 ShareVDE 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 |
