Open Archives API » URI and Content Negotiation

Persons observations shown on Open Archives are available in various serializations and (for linked data in) various representations.

Open Archives implements the draft W3C Content Negotiation by Profile specification so client may request the desired serialization (aka mediatype) and representation (aka profile).

Note: This Open Archives implementation uses the formats attribute conforming to Mark Nottingham's Link Hint Internet Draft, which is leveraged in the Profile Negotiation I-D. The W3C Working Draft (02 October 2023) of Content Negotiation by Profile errornously uses format (without the s).

Open Archives conforms to the following two functional profiles of the W3C Content Negotiation by Profile specification:


An Open Archives URI has the format https://www.openarchieven.nl/{3 letter archive code}:{uuid}[/{token}]. In this document https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649 will be the basis for all exmaples.

Note: the previous mechanisms for linked data and non-linked data are still working and mentioned for reference purposes.


Content negotiation with query string arguments

A request for a person observation on Open Archives URI can take 2 query string arguments:

When the _profile query string argument has the value of alt, all available profiles and media types are shown in JSON. The response to request https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649?_profile=alt is:

{
	resource: "https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649",
	profiles: [
		{
			uri: "https://www.openarchieven.nl/def/a2a#",
			token: "a2a",
			media_types: [
				"application/ld+json",
				"application/n-triples",
				"text/turtle",
				"application/rdf+xml",
				"text/n3"
			]
		},
		{
			uri: "https://iisg.amsterdam/id/civ/",
			token: "civ",
			media_types: [
				"application/ld+json",
				"application/n-triples",
				"text/turtle",
				"application/rdf+xml",
				"text/n3"
			]
		},
		{
			uri: "https://personsincontext.org/model#",
			token: "pico",
			media_types: [
				"application/ld+json",
				"application/n-triples",
				"text/turtle",
				"application/rdf+xml",
				"text/n3"
			]
		}
	]
}

This response shows that the resource is available according to 3 profiles, each specified with an URI, a short name for the profile called a token and available media types. From this, valid query string arguments can be found. As example, the request of linked data in Turtle according to the Persons in Context model is https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649?_mediatype=text/turtle&_profile=pico or instead of token use of uri profile https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649?_mediatype=text/turtle&_profile=https://personsincontext.org/model%23: 

prefix oa: <https://www.openarchieven.nl/id/> .
@prefix pico: <https://personsincontext.org/model#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix sdo: <https://schema.org/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

oa:record_rat_48c2b836-385f-11e0-bcd1-8edf61960649_Person_22f30464-3867-11e0-bcd1-8edf61960649
  a pico:PersonObservation ;
  prov:hadPrimarySource oa:record_rat_48c2b836-385f-11e0-bcd1-8edf61960649 ;
  pico:hasRole "Moeder" ;
  sdo:children oa:record_rat_48c2b836-385f-11e0-bcd1-8edf61960649_Person_22f2ae9c-3867-11e0-bcd1-8edf61960649 ;
  sdo:spouse oa:record_rat_48c2b836-385f-11e0-bcd1-8edf61960649_Person_22f2da16-3867-11e0-bcd1-8edf61960649 ;
  sdo:gender sdo:Female ;
  sdo:name "Cornelia Verhulst" ;
  sdo:familyName "Verhulst" ;
  sdo:givenName "Cornelia" .

....

oa:record_rat_48c2b836-385f-11e0-bcd1-8edf61960649
  a sdo:ArchiveComponent ;
  sdo:additionalType  ;
  sdo:name "Regionaal Archief Tilburg (Tilburg), Bron: boek, Periode: 1819, Geboorteregister 1819, 21"@nl ;
  sdo:dateCreated "1819-04-12"^^xsd:date ;
  sdo:locationCreated "Alphen en Riel" ;
  sdo:associatedMedia [
    a sdo:ImageObject ;
    sdo:position "1" ;
    sdo:url "https://images.memorix.nl/tlb/thumb/640x480/c36e8493-0064-4e9b-7f75-9b40b38663b0.jpg" ;
    sdo:embedUrl "https://www.regionaalarchieftilburg.nl/zoek-een-persoon/deeds/48c2b836-385f-11e0-bcd1-8edf61960649" ;
    sdo:thumbnail "https://images.memorix.nl/tlb/thumb/250x250/c36e8493-0064-4e9b-7f75-9b40b38663b0.jpg"
  ] ;
  sdo:url "https://www.regionaalarchieftilburg.nl/zoek-een-persoon/deeds/48c2b836-385f-11e0-bcd1-8edf61960649" ;
  sdo:dateModified "2011-07-27"^^xsd:date .

The non-standard way to get the same result on Open Archives is https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649/ttl:pico. When a profile token is ommitted, eg. https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649/ttl, Open Archives defaults to the A2A information model.


Content negotiation with HTTP headers

To indicate with HTTP headers which media types can be handled by the client, the Accept header can be used. Equivalently, the Accept-Profile header is used to indicate the profile (by URI or token). Multiple values (with q value to specify the desirability) can be given. For the example resource the request could be:

$ curl -H "Accept: text/turtle" -H "Accept-Profile: pico" https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649
or
$ curl -H "Accept: text/turtle" -H "Accept-Profile: https://personsincontext.org/model#" https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649

The non-standard way to get the same result on Open Archives is:

$ curl -H "Accept: text/turtle+pico" https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649

Note: when no valid Accept header is given or the URL is requested by user in a brower, Open Archives defaults to text/html.


406 not acceptable

When an invalid _mediatype query parameter/Accept header or invalid _profile query parameter/Accept-Profile header is provided by the client, an HTTP 406 not acceptable error is returned. For convenience, a list of valid values is returned in plain text in the body of the response.

Note: this part is not explicitly descibed in https://www.w3.org/TR/dx-prof-conneg/ ?!


Link HTTP headers

Every repsonse from Open Archives includes a Link HTTP header in a comma separated list:

Note: the Link HTTP headers are only present in RDF responses, for HTML see the next section.


Language selection and Link headers for text/html mediatype

By default the language of the HTML is based on the Accept-Language header. Accepted languages are nl (Dutch), en (English), de (German) and fr (French).

Alternatively a language token can be appended to the Open Archives URI (eg. https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/de) or the lang query parameter can be used (eg. https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c?lang=fr). HTML available in other languages is shown via alternate links, see below. Note: the language selection only impacts text/html, not the other mediatypes.

$ curl  -H 'Accept: text/html' https://www.openarchieven.nl/rat:48c2b836-385f-11e0-bcd1-8edf61960649

<!DOCTYPE html>
<html lang="nl">
<head>
....
<title>Geboorte Johannes Christiaan Servaas op 18 november 1824 te Leiden » Open Archieven
<link rel="canonical" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c">
<link rel="alternate" hreflang="nl" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/nl">
<link rel="alternate" hreflang="en" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/en">
<link rel="alternate" hreflang="fr" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/fr">
<link rel="alternate" hreflang="de" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/de">
<link rel="alternate" hreflang="x-default" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c">
<link rel="alternate" type="text/turtle" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/ttl">
<link rel="alternate" type="application/n-triples" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/nt">
<link rel="alternate" type="application/json" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/json">
<link rel="alternate" type="application/xml" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/xml">
<link rel="alternate" type="application/vnd.familysearch.gedcom" href="https://www.openarchieven.nl/elo:f5169776-db74-70a3-51e3-20c15291429c/gedcom">
....
</body>
</html>

Other Accept values and "token path appends" for non-linked and linked data



TODO

Resource parts

Described above are the "metadata object identifiers". The "real world object" identifiers are the form https://www.openarchieven.nl/id/{record|person|event|relationep|relatiopp|source}_{3 letter archive code}_{uuid}_{part selector}. These URI's resolve to the resource in a RDF format (according to specified HTTP Accept header). This current functionality should also work with Content Negotiation by Profile. Also, HTTP 303 See also should be fully implemented and documented.

Find your ancestors and publish your family tree on Genealogy Online via https://www.genealogieonline.nl/en/