Serve JSKOS objects in multiple formats over HTTP, in particular HTML and RDF
This web service can be put in front of JSKOS (0.5.4) data sources to provide RDF serializations and browseable HTML display of controlled vocabularies at a common base URL.
Clone from git repository.
git clone https://github.com/gbv/jskos-proxy.git
cd jskos-proxy
npm ci
Instances of jskos-proxy are configured with environment variables, in local file .env
, and files in an optional configuration directory. The following keys are supported:
PORT
- which port to run the service on (default:3555
)NAMESPACE
- URI namespace of all objects served via this proxy. Must end with a slash (default:http://example.org/
)BASE
- Path under which the application will be hosted on. Must end with a slash. (Default:/
)- If
NAMESPACE
ishttp://example.org/some-path/
, buthttp://example.org/
itself is not served by jskos-proxy, you need to setBASE
to/some-path/
.
- If
BACKEND
- JSKOS API base URLTITLE
- Title of the service (defaultJSKOS Proxy
)
QUICK_SELECTION
- comma separated list of vocabulary URIs to prominently show at the start page
A configuration directory under config/
can be provided with environment variable CONFIG
. It must contain:
- file
config.env
with configuration keys documented above - CSS file
style.css
(can be empty) - a Header Vue.js component in
Header.vue
(if not necessary, please provide an empty<template />
tag); the content will be shown below the header - a Footer Vue.js component in
Footer.vue
(if not necessary, please provide an empty<template />
tag); the content will be shown next to the logo in the footer (the footer is set todisplay: flex;
)
The config/
directory already contains some examples for some known terminology services. To try out one of these examples, set nothing but CONFIG
, e.g. CONFIG=rvk
.
For development:
npm run dev
Most changes should cause either the back-end or the front-end to reload automatically if necessary, but sometimes it might be required to stop and restart the dev server for changes to apply.
For production (less verbose logging, no reload), first build the Vue front-end and then start the server:
npm run build
npm run start
The application should be put behind a reverse HTTP proxy to serve URLs starting with configured NAMESPACE
, e.g.
# Apache
ProxyPass /terminology/ http://localhost:3555/terminology/
ProxyPassReverse /terminology/ http://localhost:3555/terminology/
# Nginx
location /terminology/ {
proxy_pass http://localhost:3555/terminology/;
}
See file ecosystem.example.json
for deployment with PM2.
The proxy translates HTTP requests to an URI query. The URI is determined from query path and configured NAMESPACE
or given with optional query parameter uri
.
The URI is then looked up in the backend, and returned in a requested RDF serialization format or in HTML. The format is determined based on query parameter format
(if given) or HTTP Accept header (otherwise). The following formats are supported:
- HTML with embedded JSON-LD (default)
- JSON-LD (format
json
,jskos
orjsonld
) - NTriples (format
nt
orntriples
) - Turtle (format
ttl
orturtle
) - RDF/XML (format
rdfxml
orxml
)
See https://bartoc.org/software for a collection of software for knowledge organization systems (aka controlled vocabularies). Browsing interfaces similar to jskos-proxy are provided by Skohub and Skosmos, among other solutions.
MIT © 2024- Verbundzentrale des GBV (VZG)