Skip to content

DSP-TOOLS version on PyPI Supported Python versions License Ruff uv mypy

DSP-TOOLS Documentation

Installing dsp-tools

Install uv. On macOS and Linux, run:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then run DSP-TOOLS with uvx:

uvx dsp-tools --version

uv downloads the Python version that DSP-TOOLS requires, if your computer does not have it.

uvx keeps using the version of DSP-TOOLS that it downloaded first. To update to the latest version, run:

uvx dsp-tools@latest --version

To use the xmllib in your own scripts, create a uv project in the folder of your scripts and add dsp-tools to it:

uv init
uv add dsp-tools

To update dsp-tools in this project, run:

uv lock --upgrade-package dsp-tools

Then run your scripts with uv run:

uv run my_script.py

🚨 If you do not use uv, make sure that your Python version is not older than the version that DSP-TOOLS requires. Otherwise, the installation can silently give you an outdated version of DSP-TOOLS.
DSP-TOOLS requires one of these Python versions:
The most recent version of DSP-TOOLS is

The dsp-tools package provides you with functionalities in the command line to interact with the DSP-API, both remote and locally. Additionally, it contains the xmllib which helps you construct the XML file required for a mass upload.

Where To Start?

dsp-tools provides you with the following core functionalities.

  • Running a Local Stack: If you want to run your own DSP stack locally, take a look here.
  • Data Modelling: There are several ways to create a data model with dsp-tools
    • Take a look at the technical specification for the JSON file.
    • Or take a look at our tool to convert Excel files into the JSON format.
    • You can create a data model on the DSP-APP. To re-use that data model on another server you can use the CLI command described here.
  • Data for Mass-Upload:
    • If you want to create the XML file required for a mass-upload onto DSP, take a look at the xmllib.
    • You can find an in-depth explanation of our XML file format here. Please note, that we recommend to use the xmllib library to create the file as we will ensure interoperability between the DSP-API requirements and your input.
    • If you want to validate and upload your XML file take a look here. Please note, that only DaSCH employees are permitted to upload data on a production server. They use the project admin account of the project.

List of CLI Commands

The following CLI Commands are available, listed here in alphabetical order.

Command Description Documentation
create Create a project on a server from a JSON file
uvx dsp-tools create project.json		 →
excel2json Create the project definition JSON from Excel files
uvx dsp-tools excel2json excelfolder project.json		 →
excel2lists Create the list section of the project JSON
uvx dsp-tools excel2lists excelfolder lists.json		 →
excel2properties Create the properties section of the JSON
uvx dsp-tools excel2properties properties.xlsx properties.json		 →
excel2resources Create the resource section of the JSON
uvx dsp-tools excel2resources resources.xlsx resources.json		 →
get Retrieve a project definition JSON from a server
uvx dsp-tools get -P 0XXX project.json		 →
id2iri Replace internal IDs with IRIs in an XML file
uvx dsp-tools id2iri new_data.xml id2iri_mapping.json		 →
ingest-files Kick off the ingest process and save the mapping CSV
uvx dsp-tools ingest-files 0XXX		 →
ingest-xmlupload Create resources from XML after files are ingested
uvx dsp-tools ingest-xmlupload data.xml		 →
mapping config Create a mapping YAML config file
uvx dsp-tools mapping config -P 0XXX --ontology my-onto		 →
mapping update Replace external ontology mappings from an Excel file
uvx dsp-tools mapping update 0XXX-my-onto-mapping.yaml		 →
migration config Create a migration config YAML file
uvx dsp-tools migration config -P 0XXX		 →
migration complete Execute a complete migration
uvx dsp-tools migration complete migration-0XXX.yaml		 →
migration export Download project data from the source server
uvx dsp-tools migration export migration-0XXX.yaml		 →
migration import Import a downloaded export to another server
uvx dsp-tools migration import migration-0XXX.yaml		 →
migration clean-up Clean up local files and server references
uvx dsp-tools migration clean-up migration-0XXX.yaml		 →
old-excel2json Create project definition JSON using the old Excel format
uvx dsp-tools old-excel2json excelfolder project.json		 →
old-excel2lists Create the list section using the old Excel format
uvx dsp-tools old-excel2lists excelfolder lists.json		 →
resume-xmlupload Resume a previously interrupted xmlupload
uvx dsp-tools resume-xmlupload		 →
start-stack Start a local DSP stack
uvx dsp-tools start-stack		 →
stop-stack Stop the local DSP stack
uvx dsp-tools stop-stack		 →
update-legal Move legal metadata onto <bitstream> attributes
uvx dsp-tools update-legal [mandatory options] data.xml		 →
upload-files Upload multimedia files referenced in an XML file
uvx dsp-tools upload-files data.xml		 →
validate-data Validate XML data against a data model on a server
uvx dsp-tools validate-data data.xml		 →
xmlupload Create resources from an XML file on a server
uvx dsp-tools xmlupload data.xml		 →