Skip to content
Knowledge Organization, Representation, and Annotation
Scala JavaScript TypeScript Ruby CSS Lua Other
Branch: develop
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docker feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
docs feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
knora-ontologies <a> tag mapping to manage URL #fragment (#1440) Sep 25, 2019
project feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
salsah1 Generate ARK URLs for resources (#1161) Jan 21, 2019
salsah2 build (docker): fix codacy issues (#1030) Nov 2, 2018
sipi feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
test-data/v7.0.0 feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
travis build (travis): update GraphDB license (#1099) Dec 10, 2018
triplestores refactor (webapi): remove unnecessary actor pools (#979) Sep 7, 2018
upgrade <a> tag mapping to manage URL #fragment (#1440) Sep 25, 2019
webapi feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
.dockerignore feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
.gitignore feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
.grenrc.js chore: change gren config (#1415) Aug 30, 2019
.travis.yml feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
Contributors.md releasing-v5.0.0 (#1205) Feb 5, 2019
KnoraBuild.sbt feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
LICENSE.md Update LICENSE.md Jan 25, 2016
Makefile feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
README.md feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
RELEASING.md chore: change gren config (#1415) Aug 30, 2019
codeship-services.yml build (webapi): library upgrades (codeship part 1) (#653) Feb 1, 2018
codeship-steps.yml build (webapi): library upgrades (codeship part 1) (#653) Feb 1, 2018
docker-compose.yml feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019
vars.mk feat: Upgrade sipi to 2.0.1 (#1459) Oct 18, 2019

README.md

Build Status Codacy Badge

Knora

Knora (Knowledge Organization, Representation, and Annotation) is a server application for storing, sharing, and working with primary sources and data in the humanities.

It is developed by the Digital Humanities Lab at the University of Basel, and is supported by the Swiss Academy of Humanities and Social Sciences.

Knora is free software, released under the GNU Affero General Public License.

Features

  • Stores humanities data as industry-standard RDF graphs, plus files for binary data such as digitized primary sources.
    • Designed to work with any standards-compliant RDF triplestore. Tested with Ontotext GraphDB.
  • Based on OWL ontologies that express abstract, cross-disciplinary commonalities in the structure and semantics of research data.
  • Offers a generic HTTP-based API, implemented in Scala, for querying, annotating, and linking together heterogeneous data in a unified way.
    • Handles authentication and authorization.
    • Provides automatic versioning of data.
  • Uses Sipi, a high-performance media server implemented in C++.
  • Designed to be be used with SALSAH, a general-purpose, browser-based virtual research environment, as well as with custom user interfaces.

Status

Stable

Beta stage

New features under development

Requirements

For developing and testing the API server

Ontotext GraphDB is recommended. Support for other RDF triplestores is planned.

For building the documentation

See docs/Readme.md.

Try it out

Quick Installation Guide for Knora, Salsah, Sipi and GraphDB

A manual to get all mentioned components locally up and running can be found here.

Run the Knora API server

With Docker installed, run the following:

$ make stack-up

Then to create a test repository and load some test data into the triplestore:

$ make init-db-test-free

Then we need to restart the knora-stack after loading the data:

$ make stack-restart

Then try opening http://localhost:3333/v1/resources/http%3A%2F%2Frdfh.ch%2Fc5058f3a in a web browser. You should see a response in JSON describing a book.

To shut down the Knora-Stack:

$ make stack-down

Run the automated tests

Run :

$ make init-knora-test-unit-free
$ make normal-tests

How to Contribute

You can help by testing Knora with your data, making bug reports, improving the documentation, and adding features that you need.

First, open an issue to describe your problem or idea. We may ask you to submit a pull request implementing the desired functionality.

Coding conventions

Use camelCase for names of classes, variables, and functions. Make names descriptive, and don't worry if they're long.

Format your code consistently. We IntelliJ IDEA to format code, with 4 spaces indentation. Use whitespace to make your code easier to read. Add lots of implementation comments describing what your code is doing, how it works, and why it works that way.

Tests

We write automated tests using ScalaTest. You can run them from the SBT console.

There are three sets of automated tests:

  • Unit tests, route-to-route tests, and end-to-end tests are under webapi/src/test. To run these, type graphdb:test or graphdb-free:test (depending on which triplestore you're using) at the SBT console in the webapi project. To run a single test, use graphdb:test-only *NameOfTestSpec.
  • Integration tests, which can involve Sipi, are under src/it. To run these, first start Sipi, then type it:test at the SBT console in the webapi project.
  • Browser interaction tests are under salsah/src/test, and are written using Selenium. To run these, you will need to unpack the correct ChromeDriver for your platform found under salsah/lib/chromedriver and put it in the same folder. Then start Sipi and the Knora API server, and type test at the SBT console in the salsah project.

Whenever you add a new feature or fix a bug, you should add one or more tests for the change you made.

Documentation

A pull request should include tests and documentation for the changes that were made. See the documentation README for information on writing Knora documentation.

Contact information

Technical

Please use the knora-user mailing list for technical questions.

Administrative

Lukas Rosenthaler <lukas.rosenthaler@unibas.ch>

Commit Message Schema

When writing commit messages, we stick to this schema:

type (scope): subject
body

Types:

  • feature (new feature for the user)
  • fix (bug fix for the user)
  • docs (changes to the documentation)
  • style (formatting, etc; no production code change)
  • refactor (refactoring production code, eg. renaming a variable)
  • test (adding missing tests, refactoring tests; no production code change)
  • build (changes to sbt tasks, CI tasks, deployment tasks, etc.; no production code changes)
  • enhancement (residual category)

Example:

feature (resources route): add route for resource creation
- add path for multipart request
- adapt handling of resources responder

Release Versioning Convention

The Knora project is following the Semantic Versioning convention for numbering the releases as defined by [http://semver.org]:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Additionally, we will also increment the MAJOR version in the case when any kind of changes to existing data would be necessary, e.g., any changes to the Knora-Base ontologies which are not backwards compatible.

Acknowledgments

The Knora project is using YourKit for profiling.

YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.

You can’t perform that action at this time.