Cocoda Mapping Tool

A web-based tool for creating mappings between knowledge organization systems.

Try out the latest release version, the current development version, and consult the usage documentation!

Install
Usage
Configuration
Maintainers
Contribute
License

Install

Release versions

Releases can be downloaded in form of static files. Extract into a web server directory and adjust configuration file cocoda.json. You could automate download and extraction of the latest release with jq like this:

# You can also manually download the latest release here: https://github.com/gbv/cocoda/releases/latest
wget -N $(curl -s https://api.github.com/repos/gbv/cocoda/releases/latest | jq -r '.assets[].browser_download_url')
unzip cocoda-*.zip
rm cocoda-*.zip

The directory cocoda is then ready to be served with any web server.

Development versions

Alternatively, it's possible to clone the Cocoda repository:

git clone https://github.com/gbv/cocoda.git
cd cododa

Then install required Node modules with npm and run build (requires Node.js v18 or above, v20 recommended):

npm ci
npm run build

Files are created in directory dist, including the configuration file.

Serving the Files

Any web server can be used to serve Cocoda files. No special configuration is necessary. For instance using the http-server npm package to serve Cocoda at http://localhost:8000:

# serve the pre-built release
npx http-server -p 8000 cocoda/
# or serve the build version
npx http-server -p 8000 dist/

Docker

Cocoda is also available via Docker. Please refer to our Docker documentation for more information and instructions.

Usage

There is a detailled end-user manual available in German and in English. The German version will likely be more up-to-date. Documentation sources are located in directory docs.

Configuration

For the pre-built version, configuration options can be overridden by using cocoda.json in the root of the directory. The default options are given in the file config/cocoda.default.json (please consult this file for examples on how to use the configuration options). When using a manual build, create file config/cocoda.json and rebuild (npm run build) after editing (you can also run npm run build -- --config-only if you already have a build in folder dist/ and only need to update the config file). The following fields are recognized so far:

title: the main title of the instance as plain string
logos: a list of logos to display left to the title, each with subfields:
- file: image URL relative to the static directory
- alt: alternate text for the image, if the image cannot be displayed, as plain string
- url: URL to link from the logo
menu: a list of links to show in the menu, each with subfields:
- url: the link URL
- prefLabel: mapping of language codes to link titles
searchLinks: a list of search links to quickly link to external resources from concepts. Each searchlink has subfields:
- url an URL template with possible parameters {prefLabel} and/or {notation}
- prefLabel: mapping of language codes to link titles
favoriteSchemes: list of vocabulary URIs to be favorited by default.
languages: array with supported interface languages
registries: lists registries where to get data from
overrideRegistries: false (default) or true controls whether to override registries listed in config/cocoda.default.json
auth: URL to a login-server instance to be used for authentication
conceptLists: a list of concept lists. Each list can be either an object or a URL that returns a JSON object. Objects are basically JSKOS registries with required properties prefLabel and concepts. If concepts is a string, it will be considered a URL which returns a JSON array of concepts. Optional properties are notation and scopeNote.
autoRefresh: an object with auto refresh values in milliseconds. autoRefresh.mappings determines how often mappings in MappingBrowser will be reloaded (default: 10000 = every 10 seconds), autoRefresh.update determines how often Cocoda will look for an update (default: 120000 = every 2 minutes).

Using the pre-built version, the application only has to be reloaded after editing the configuration file.

Maintainers

Contribute

Your contributions to improve Cocoda are very welcome: please open a GitHub issue for feature suggestions and bug reports! See the file CONTRIBUTING.md for more information about how and where to best contribute and for development details.

See https://gbv.github.io/cocoda/ for API documentation automatically build from Node sources.

gbv / cocoda

readme