Working with DSP-TOOLS Locally

This guide walks you through working with dsp-tools on your local computer — from installation to creating and managing data models.

Prerequisites

You need to install Docker before getting started.

Installing DSP-TOOLS

To install dsp-tools, run the following command:

pip3 install dsp-tools

To update dsp-tools to the latest version, run:

pip3 install --upgrade dsp-tools

Starting the Local DSP Stack

Start Docker, then start the local DSP stack:

dsp-tools start-stack

Open http://0.0.0.0:4200/ in your browser.

Log in with:

• Username: root
• Password: test

Creating a Project

1. Click the "My account" icon on the right and select "System Administration"
2. Click "Create new project"
3. Use 0750 as a provisional shortcode — once you decide to archive your data at DaSCH, you will receive an official one
4. Choose a shortname (3–20 characters, only lowercase letters, numbers, and hyphens)
5. Choose a title for your project
6. Provide a short description in English (and optionally in other languages)
7. Add a few keywords
8. Click "Submit"

Creating a Data Model

Click "Data model" and choose "Create New."

Set a unique name for the data model, the label, and explain more details in the comment.

Now you can create classes and properties. Please see the Naming Conventions and follow them — if you do so, a documentation of your data model can be created semi-automatically.

For the different types of classes and properties, see the DSP-TOOLS documentation (Data Modelling section).

Representation Types

The following representation types are available for classes:

Controlled Vocabularies

Controlled vocabularies must be created in the separate "Controlled vocabularies" section. To use them, choose "List" as the property type.

If you have the controlled vocabulary already available in a spreadsheet, you can use the dsp-tools excel2lists command to create the lists, which you can then upload. More information and an Excel template are available in the excel2lists documentation.

Property Configuration

Decide whether a property can have multiple values or is a required field. Nothing can be saved or imported if there is no value for a required property.

Retrieving and Uploading Data Models

Retrieve the data model you created locally (assuming 0750 is the shortcode — replace my-data-model with your chosen name):

dsp-tools get -P 0750 my-data-model.json

For other commands to interact with a server, see the data model CLI documentation.

The data model editor does not yet have the capability to add mappings to reference ontologies such as dcterms, schema, skos, or cidoc-crm. These must be added manually in the JSON file.

Once you have a data model locally, you can upload it to your local DSP stack. Note that there can only be one data model with the same shortcode at a time:

dsp-tools create my-data-model.json

Stopping the Stack

To close the stack and remove everything:

dsp-tools stop-stack

Further Resources

• DSP-TOOLS Documentation
• Naming Conventions
• User Profile Guide