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 and uv before getting started.

Running DSP-TOOLS

DSP-TOOLS runs via uvx, which executes the tool directly without a separate install or upgrade step.

Starting the Local DSP Stack

Start Docker, then start the local DSP stack:

uvx 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 uvx 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):

uvx 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:

uvx dsp-tools create my-data-model.json

Stopping the Stack

To close the stack and remove everything:

uvx dsp-tools stop-stack

Further Resources

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