"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

Spatial Information Services Stack Vocabulary Service (SISSVoc) 3.0 API

Specification for a RESTful vocabulary-service API, following the Linked Data API. This is a complete re-design of the SISSvoc interface, and is not backward compatible with previous versions of SISSvoc.

Link to Implementation Pages --> NEW Vocabulary Service 3.0 Implementation Pages

Requirements

  1. Clients want to be able to
    • discover a set of vocabulary items that satisfy some basic criteria - typically a term and often related terms
    • get a complete description of an item from the vocabulary
    • get a suitable indication if the 'term does not exist in the vocabulary'
  2. The API should support both human users and machine-machine interactions
  3. It should be implemented according to current web practice, in particular
    • providing RESTful behaviour
    • following semantic web conventions regarding information- vs non-information-resources, Cool URIs, etc

Assumptions

  1. Vocabularies will be formalized using SKOS, or at least will be decorated by SKOS terms and properties.This means
    • vocabulary items are identified using URIs.
    • 'labels' are merely for the human UI. A concept can have labels in many languages
    • items can be members of schemes and collections
    • basic thesaurus relationships (broader, narrower, related) are supported natively
  2. Vocabularies will be stored in RDF triple-store, with SPARQL or another low-level RDF API as the basic interface
  3. Clients should not have to use SPARQL
  4. Vocabularies are strongly governed, so the normal client requires read-only access
  5. The RDF namespace of the Concepts and other SKOS elements need not, and in general will not, be the same as the http domain of the server implementing this service.
    • The same content may be served from multiple locations.
    • The owner of the concept namespace MAY configure their server so that the URIs re-direct to the 'describe resource identified by URI' request (#0 below) on a server that hosts their content, with a HTTP 302 or 303 response code. This follows Semantic Web conventions for redirecting from a URI for a non-information-resource (here: a Concept) to a URL for a document describing that resource (here: the vocabulary-service response).
Items 2-4 are essentially same rationale for the development of the Linked Data API (LDA). The LDA presents patterns for simplified queries into relatively homogeneous (RDF) collections. Vocabularies formalized with SKOS fit that scenario.

Here we propose a LDA-based vocabulary API which explicitly leverages the SKOS model and terminology, and also show how this could be implemented in SPARQL. SKOS terms appear explicitly in the URIs.

Interface

API

NOTE 1: Parameterized requests use the ?P=V style, and the ../p1/v1 style is used for resource types and paths.

NOTE 2: Links to SPARQL patterns for the select phase of the query are given. Configuration of a SISSSvoc deployment may not use these SPARQL queries directly.
Basic template Example resource SPARQL pattern for GET
{root} http://auscope-services-test.arrc.csiro.au/elda-demo/api/isc2009 - not yet at the intended location Landing page for this vocabulary service, including form-style query builders for the URI templates described here Static document
{root}/resource?uri={URI} http://def.seegrid.csiro.au/sissvoc/isc2009/resource?uri=http://resource.geosciml.org/classifier/ics/ischart/Cambrian Description of the resource identified by URI - not limited to any specific type.

See note below for interpretation in Cool URI terms
SISSvoc30SPARQLPatterns#A_0
{root}/conceptscheme http://def.seegrid.csiro.au/sissvoc/isc2009/conceptscheme List of all concept schemes 1
{root}/collection http://def.seegrid.csiro.au/sissvoc/isc2009/collection List of all concept collections 2
{root}/concept http://def.seegrid.csiro.au/sissvoc/isc2009/concept List of all concepts 3
{root}/concept?anylabel={text} http://def.seegrid.csiro.au/sissvoc/isc2009/concept?anylabel=Cambrian List of concepts where a label matches this text 4
{root}/concept?labelcontains={text} http://def.seegrid.csiro.au/sissvoc/isc2009/concept?labelcontains=Cambrian List of concepts where a label contains this text 5
{root}/concept/broader?uri={URI} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/broader?uri=http://resource.geosciml.org/classifier/ics/ischart/Cambrian List of concepts skos:broader than the concept identified by URI 6
{root}/concept/narrower?uri={URI} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/narrower?uri=http://resource.geosciml.org/classifier/ics/ischart/Cambrian List of concepts skos:narrower than the concept identified by URI 7
{root}/concept/broaderTransitive?uri={URI} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/broaderTransitive?uri=http://resource.geosciml.org/classifier/ics/ischart/Cambrian List of concepts skos:broaderTransitive than the concept identified by URI 8
{root}/concept/narrowerTransitive?uri={URI} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/narrowerTransitive?uri=http://resource.geosciml.org/classifier/ics/ischart/Cambrian List of concepts skos:narrowerTransitive than the concept identified by URI 9
{root}/concept/broader?anylabel={text} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/broader?anylabel=Cambrian List of concepts skos:broader than a concept with a label that matches this text 10
{root}/concept/narrower?anylabel={text} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/narrower?anylabel=Cambrian List of concepts skos:narrower than a concept with a label that matches this text 11
{root}/concept/broaderTransitive?anylabel={text} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/broaderTransitive?anylabel=Cambrian List of concepts skos:broaderTransitive than a concept with a label that matches this text 12
{root}/concept/narrowerTransitive?anylabel={text} http://def.seegrid.csiro.au/sissvoc/isc2009/concept/narrowerTransitive?anylabel=Cambrian List of concepts skos:narrowerTransitive than a concept with a label that matches this text 13

Abbreviations

Use of HTTP

The following may be implemented using the HTTP layer
  • read access using HTTP GET
  • update using HTTP PUT, DELETE (TODO)
  • format negotiation using HTTP Accept header
  • language negotiation using HTTP Language header
  • existence verification though 2** and 3** HTTP response codes (or non-existence through 4**)
NOTE: PUT and DELETE requests should be subject to authorization

Get Description request

This is the basic "tell me what you know about the resource identified by this URI" request. Note that the service has a different URI to the resource. The same resource may also be described by other services.

In RESTful terms, this entire URI identifies a document (or graph) describing the resource identified by URI,
i.e. the resource foaf:isPrimaryTopicOf this document

If you have access to the HTTP server configuration for the URI domain(s), it may be configured to redirect a URI request to this document, using the 303 Cool URI pattern

Options

The Linked Data API defines a number of standard options and parameters, including

todo:

Different viewers can be used to get the service to return different sets of information for the result-set. So far we have mostly used the defaults, but there is opportunity for more work here.
  • other views
  • Update interface (using PUT, DELETE etc?, or using SPARQL Update)
  • Matching to external vocabularies
    • allow a user to add 'matches' relationships

eResearch Poster:

Topic revision: r58 - 12 Oct 2012, SimonCox
 

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).