Page tree
Contents

Introduction

Vocabularies published through RVA's SISSVoc instance are made available through a selection of linked data endpoints.

The rationale for these endpoints is provided in this paper:

Simon J D Cox, Jonathan Yu and Terry Rankine, SISSVoc: A Linked Data API for access to SKOS vocabularies, Semantic Web Journal, to appear. Available at: http://www.semantic-web-journal.net/system/files/swj880.pdf.

SISSVoc works with SKOS vocabularies. For example, the /concept endpoint produces a list of SKOS Concepts (instances of the skos:Concept type). If you use these endpoints to access a non-SKOS vocabulary that has been published through SISSVoc, most likely there will be no results; only the /resource?uri={IRI} endpoint will return anything of interest.

Working with JavaScript-based services

Cross-Origin Resource Sharing (http://enable-cors.org/) is enabled for linked data endpoints served from vocabs.ands.org.au. This means that endpoint URLs can be used by JavaScript code in your own web applications.

Endpoint templates

 

Endpoint templateTypeQuery
/collectionListList of all Collections and OrderedCollections
/conceptListList of all Concepts
/concept/broader?anylabel={text} ListList of all Concepts broader than the one where a label matches the text
/concept/broader?uri={baseConcept} ListList of all Concepts broader than the one identified by this IRI
/concept/broaderTransitive?anylabel={text} ListList of all Concepts broaderTransitive than the one where a label matches the text
/concept/broaderTransitive?uri={baseConcept} ListList of all Concepts broaderTransitive than the one identified by this IRI

/concept/narrower?anylabel={text}

ListList of all Concepts narrower than the one where a label matches the text

/concept/narrower?uri={baseConcept}

ListList of all Concepts narrower than the one identified by this IRI
/concept/narrowerTransitive?anylabel={text} ListList of all Concepts narrowerTransitive than the one where a label matches the text
/concept/narrowerTransitive?uri={baseConcept} ListList of all Concepts narrowerTransitive than the one identified by this IRI
/concept/topConceptsListList of all topConcepts
/concept/topConcepts?scheme={schemeIRI} ListList of all topConcepts that belong to the given ConceptScheme
/concept?anylabel={text} ListList of all Concepts where a label matches the text
/concept?labelcontains={text} ListList of all Concepts where a label contains the text, any language, case-insensitive
/conceptschemeListList of all ConceptSchemes
/resource?uri={IRI} ItemDescribe the given resource

Notes:

  • An endpoint template of type “List” returns a list of zero or more items. An endpoint template of type “Item” returns at most one item.
  • Where a template includes a component in italics, that component, including surrounding braces, is to be replaced by specific content.
  • For historical reasons, the endpoint templates use ?uri= instead of the more correct ?iri=.
  • The default format of the result is HTML. Other formats may be specified by including a “suffix” component in the URL. If the endpoint template includes a question mark, the suffix is placed before the question mark. For example, /concept/narrower.json?uri={baseConcept} will return data in JSON format.
    • Supported format suffixes are: .html.json.rdf (returns RDF/XML), .text (returns JSON, but with a text MIME type), .ttl, and .xml (returns XML in the ELDA library's own schema).
  • SISSVoc is based on the ELDA library, which implements the Linked Data API (https://github.com/UKGovLD/linked-data-api/blob/wiki/Specification.md). Therefore, URLs can make use of the other features provided by the ELDA library.

Constructing a URL

URLs that access the linked data endpoints are constructed from the following components in sequence. (The value in the Example column for vocabulary identifier is artificially chosen; it does not correspond to a vocabulary published at RVA.)

ComponentConstructionExample
The RVA hostname and API prefix

http://vocabs.ands.org.au/repository/api/lda/
or
https://vocabs.ands.org.au/repository/api/lda/

http://vocabs.ands.org.au/repository/api/lda/

The vocabulary identifier

Vocabulary owner, vocabulary title, version title, separated by slashes

ands/nal-agricultural-thesaurus/nal-thesaurus-2015-edition
The endpoint selection, including optional parameterMake a selection from the Endpoint templates table above/concept

Combining the values in the example column yields: http://vocabs.ands.org.au/repository/api/lda/ands/nal-agricultural-thesaurus/nal-thesaurus-2015-edition/concept (Again, please note that this URL is a sample only, and does not resolve.)

Notes:

  • The components of the vocabulary identifier are turned into “slugs” (https://en.wikipedia.org/wiki/Semantic_URL#Slug) before inclusion in the URL. In practice, this means conversion to lower case, and the replacement of all non-alphanumeric data with hyphens.  You do not have to guess what a slug will be; each vocabulary available through SISSVoc on RVA has, on its view page, a sample link to a SISSVoc endpoint.

Special URLs for current versions

RVA supports the publication of multiple versions of a vocabulary; access to the linked data endpoints of the different versions is effected by using the different version titles in the vocabulary identifier components of the URL, as shown in the previous section. However, there is an additional “shortcut” provided to access the endpoints of the version which has been tagged as the “current” version in the portal. In addition to the endpoints available with the version title, the same endpoints are also available automatically with current as the version title. For example, if the version with version title nal-thesaurus-2015-edition is tagged as the current version, the following two URLs would generate the same page:

  • http://vocabs.ands.org.au/repository/api/lda/ands/nal-agricultural-thesaurus/nal-thesaurus-2015-edition/concept
  • http://vocabs.ands.org.au/repository/api/lda/ands/nal-agricultural-thesaurus/current/concept  
  • No labels