Getting Started with the Knora API Server

Choosing and Setting Up a Triplestore

The Knora API server requires a standards-compliant RDF triplestore. A number of triplestore implementations are available, including free software as well as proprietary options. The Knora API server is tested and configured to work out of the box with the following triplestores:

  • Ontotext GraphDB, a high-performance, proprietary triplestore. The Knora API server is tested with GraphDB Standard Edition and GraphDB Free (which is proprietary but available free of charge).
  • Apache Jena, which is free software. Knora comes bundled with Jena and with its standalone SPARQL server, Fuseki.

See the chapters on Starting Fuseki 3 and Starting GraphDB-SE for more details.

Creating Repositories and Loading Test Data

To create a test repository called knora-test and load test data into it, go to webapi/scripts and run the script for the triplestore you have chosen.

  • For Fuseki, run fuseki-load-test-data.sh.

  • For GraphDB:
    • If you are running GraphDB directly from its installation directory (using its graphdb script), run graphdb-se-local-init-knora-test.sh.
    • If you are running GraphDB from a Docker image, run graphdb-se-docker-init-knora-test.sh.

You can create your own scripts based on these scripts, to create new repositories and optionally to load existing Knora-compliant RDF data into them.

If you are using GraphDB, you must create your repository using a repository configuration file that specifies the file KnoraRules.pie as its owlim:ruleset. This enables RDFS inference and Knora-specific consistency rules. When using GraphDB, the Knora API server uses RDFS inference to improve query performance. The Knora-specific consistency rules help ensure that your data is internally consistent and conforms to the Knora ontologies.

When testing with GraphDB, you may sometimes get an error when loading the test data that says that there are multiple IDs for the same repository knora-test. In that case, something went wrong when dropping and recreating the repository. You can solve this by deleting the repository manually and starting over. Make sure you don’t delete important data. To delete the repository, stop GraphDB, delete the data directory in your GraphDB installation, and restart GraphDB.

Creating a Test Installation

TODO: write subsections like this:

  • Download the Knora API Server and Sipi from GitHub
  • Configure
  • Run

Transforming Data When Ontologies Change

When there is a change in Knora’s ontologies or in a project-specific ontology, it may be necessary to update existing data to conform to the new ontology. This can be done directly in SPARQL, but for simple transformations, Knora includes a command-line program that works on RDF data files in Turtle format. You can run it from SBT:

> run-main org.knora.webapi.util.TransformData --help
[info] Running org.knora.webapi.util.TransformData --help
[info]
[info] Updates the structure of Knora repository data to accommodate changes in Knora.
[info]
[info] Usage: org.knora.webapi.util.TransformData -t [deleted|permissions|strings|standoff|all] input output
[info]
[info]   -t, --transform  <arg>   Selects a transformation. Available transformations:
[info]                            'deleted' (adds missing 'knora-base:isDeleted'
[info]                            statements), 'permissions' (combines old-style
[info]                            multiple permission statements into single permission
[info]                            statements), 'strings' (adds missing valueHasString),
[info]                            'standoff' (transforms old-style standoff into
[info]                            new-style standoff), 'creator' (transforms existing
[info]                            'knora-base:Owner' group inside permissions to
[info]                            'knora-base:Creator'), 'owner' (gives
[info]                            'knora-base:Creator' CR permissions to correspond to
[info]                            the previous behaviour for owners - use with care as
[info]                            it will add permissions that where not there before),
[info]                            'all' (all of the above minus 'owner')
[info]       --help               Show help message
[info]
[info]  trailing arguments:
[info]   input (required)    Input Turtle file
[info]   output (required)   Output Turtle file

The currently available transformations are:

deleted
Adds knora-base:isDeleted false to resources and values that don’t have a knora-base:isDeleted predicate.
permissions
Combines old-style permission statements (hasViewPermission, hasModifyPermission, etc.) into one hasPermissions statement per resource or value, as described in the section Permissions in The Knora Ontologies.
strings
Adds missing valueHasString statements to Knora value objects.
standoff
Transforms old-style standoff markup (containing tag names as strings) to new-style standoff markup (using different OWL class names for different tags).
creator
Transforms existing knora-base:Owner group inside permissions to knora-base:Creator.
owner
Gives knora-base:Creator CR permissions to correspond to the previous behaviour for owners. Use with care as it will add permissions that where not there before.
all
Runs all of the above transformations.

Transformations that are not needed have no effect, so it is safe to use -t all.

The program uses the Turtle parsing and formatting library from RDF4J. Additional transformations can be implemented as subclasses of org.eclipse.rdf4j.rio.RDFHandler.