Skip to content

Joining Pelagios

Jump to bottom Edit New page
John Muccigrosso edited this page Jun 22, 2018 · 7 revisions

Pelagios (Greek for 'of the Sea') is a community network that facilitates linking of online resources that document the past, based on the places they refer to. From the large numismatic database to the personal Flickr photostream, each of our partner datasets represents one piece of the puzzle. Pelagios combines these pieces into a coherent whole that enables connection, exchange and discovery - just as the Mediterranean Sea did for the Ancient World.

In principle, any resource that is published online, and which contains references to places can be linked to the Pelagios network. Some examples for this include:

  • Literary texts that include mentions of places
  • Maps
  • Images (photographs, drawings) of places of historical relevance
  • Database records of objects located at, found at, or relevant to the history of a place, such as archaeological finds or works of art

How Do I Join?

The key pre-requisite to join Pelagios is that your data is available online. Or in other words: that you have a Web site set up where users can find - under stable URLs - information about each object you want to link up with Pelagios.

The next step is to create a Pelagios Dataset Summary of your site. This summary lists all your objects, along with some basic metadata about them (e.g. title, description, date, provenance information, etc.). Most importantly, the summary must also list the URL for each object, i.e. where you host information about it, and information about which places each object is related to (and how it is related to them).

The summary is separate from your data (also in terms of licensing!), and you should publish it as one big (compressed) text file (or several, if necessary), under an open license such as CC0 or ODC-BY.

How Do I Use Pelagios Data?

Since all our members publish their dataset summaries under open licenses - and in a uniform format - anyone (member or not) can immediately grab the data and mix, match & use it for their own purposes. To make discovery and re-use easier, we are also hard at work setting up an API to the Pelagios network. Find out more about how to use it here.

The Dataset Summary

The dataset summary needs to be formatted according to a specific syntax, and be encoded as RDF, the "markup language of the Semantic Web". But no need to panic. Getting the syntax right is less complicated than it sounds, and we have some examples to guide you.

What may cost you some time, however, is that you must align your place references with a gazetteer. Gazetteer alignment is at the heart of the Pelagios network. By using the same "vocabulary" when referring to places, you are implicitly connecting your data with other datasets on the Web, on a global scale.

Depending on the nature of your data, different gazetteers may be suitable as a basis for alignment. At the moment, we support the following gazetteers:

Note: in case you maintain your own historical gazetteer (or "dataset of places", rather than "dataset of objects"), please consider linking it up to Pelagios. You need to set up a similar summary file, although with a slightly different format. Read more about it here.

Minimum Example

The RDF snippet below shows a minimum dataset summary example. It lists a single item that is related to a single place (its findspot). The example is written in Turtle notation, one of the (in our opinion, most human-readable) ways in which RDF can be published.

@prefix cnt: <http://www.w3.org/2011/content#> . 
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix oa: <http://www.w3.org/ns/oa#> .
@prefix pelagios: <http://pelagios.github.io/vocab/terms#> .
@prefix relations: <http://pelagios.github.io/vocab/relations#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema> .
 
# An object you want to link to Pelagios
<http://example.org/pelagios/dump.ttl#items/00l>
   a pelagios:AnnotatedThing ;

 # Title and homepage URL are MANDATORY
 dcterms:title "Honorific inscription of Ostia" ;
 foaf:homepage <http://edh-www.adw.uni-heidelberg.de/...> ;

 # Everything else OPTIONAL (but highly encouraged
 dcterms:description "Honorific inscription, findspot Ostia" ;

 # Use ISO 8601 (YYYY[-MM-DD) or time interval (<start>/<end>)
 # to express date information
 dcterms:temporal "366/402" ;

 # Additionally, we encourage the use of (one or multiple)
 # PeriodO identifiers to denote time periods 
 dcterms:temporal <http://n2t.net/ark:/99152/p03wskd389m> ; # Greco-Roman

 # To express an object's language (e.g. in case of literature, 
 # inscriptions, etc.), use RFC 5646 format
 dcterms:language "la" ;

 # Feel free to assign 'tags' to your data
 dcterms:subject "inscription" ;
 .
 

# Objects are 'annotated' with any number of gazetteer references
<http://example.org/pelagios/dump.ttl#items/00l/annotations/01>
   a oa:Annotation ;

 # MANDATORY: the 'annotation target' is the URI of your object;
 # the 'annotation body' is the gazetteer reference
 oa:hasTarget <http://example.org/pelagios/dump.ttl#items/00l> ;
 oa:hasBody <http://pleiades.stoa.org/places/422995> ;

 # OPTIONAL: extra metadata about the nature of the place reference
 pelagios:relation relations:foundAt ;
 oa:hasBody [ cnt:chars "POINT (41.755740099 12.290938199)";
              dcterms:format "application/wkt" ] ;
 oa:annotatedAt "2014-11-05T10:18:00Z"^^xsd:date ;
 .

We are maintaining a list with real-world examples from our partners here.

The VoID File

Once you have all your data set up, mapped your place references to gazetteers, and posted your dataset summary file online, there is one last tiny thing you need: a separate, small RDF file which acts as entry point to your data and contains global descriptive information: what's inside the dataset is, who's publishing it, under what license, etc. This file must also contain the links to all your dataset summary files, so that they can be harvested easily.

We use the RDF Vocabulary of Interlinked Datasets (VoID) to encode this information. A minimum, Pelagios-specific example is below.

@prefix : <http://my-domain.org/my-data/> .
@prefix void: <http://rdfs.org/ns/void#> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .

:my-dataset a void:Dataset;
  dcterms:title "My Archaeological Dataset";
  dcterms:publisher "My Institution or Project";
  foaf:homepage <https://my-domain.org/>;
  dcterms:description "A dataset of archaeological items.";
  dcterms:license <http://opendatacommons.org/licenses/by/>;

  # This is VERY important
  void:dataDump <http://my-domain.org/downloads/pelagios.ttl> ;
  .

We are maintaining a list with real-world examples from our partners here.

Advanced Topics

There are a lot more things you can encode in your dataset summary. For example, you can:

  • subdvide your data in to subsets
  • publish hierarchical objects (e.g. literary works subdivided into books, chapters, sections, etc.)
  • add links to images and thumbnails
  • link to your IIIF image endpoint
  • add bibliographic citations
  • assign global identifiers (such as a Wikidata or CTS URIs) which will create further connections to other people's data
  • add context to the place annotation, e.g. through a text or image snippet in case of a written place reference in a document

We are working on documentation (and the tech to support it), so bear with us. And of course we are happy to hear your input!

Add a custom footer
Add a custom sidebar
Clone this wiki locally