Inputs
Most of zen-do’s functionality takes one or more of these main inputs:
.zenodo.toml metadata file
The only allowable metadata file format that zen-do uses is TOML, which is a simple, human-readable format that is easy to write and read. Why TOML rather than Zenodo’s suggested JSON format? JSON is not a friendly format for humans to write and read, it doesn’t allow comments, and doesn’t support multi-line strings, which can be useful for writing long descriptions. TOML is the opposite, as it allows comments, multi-line strings, and is more human-friendly.
The file is named .zenodo.toml and contains all the metadata for a Zenodo deposit. It should represent the “source of truth”, as any action taken by zen-do when interacting with the Zenodo API will use this file and overwrite anything in the Zenodo deposit.
The .zenodo.toml file can be converted to and from other formats, such as .zenodo.json, _quarto.yml, pyproject.toml, and CITATION.cff (filling in the relevant fields in those other formats) using the convert command. This command is the only command that takes other formats as input.
We use the design pattern of “one .zenodo.toml file for one Zenodo deposit”, so this file must be given (or present in the working directory) for many of the actions to work. There must also be a unique “related identifier” for this (new or existing) deposit added to this .zenodo.toml file in order to identify it within the list of deposits of a user’s account. This is described in more detail in the interface documentation.
For repositories that have or will have multiple deposits, there will also be multiple .zenodo.toml files, one for each deposit. For most use-cases, you would store the .zenodo.toml file in the same folder as the file that will be uploaded to the deposit as its content. For example, in a research project repository, there may be a deposit for the paper in docs/paper/paper.pdf with the metadata in docs/paper/.zenodo.toml and a deposit for the data in data/ with the metadata in data/.zenodo.toml. This way, the metadata is kept close to the content it describes.
However, sometimes multiple deposits might describe content in the same folder. For example, a repository that has teaching material source files could be built into an HTML website and a PDF. In this case, the metadata file for the repository source files might be in .zenodo.toml, while the metadata for the PDF itself (not the source files) could be in .pdf.zenodo.toml (or .book.zenodo.toml if the output is a book). In this case, the metadata files are kept in the same location but have different names to reflect their contents.
Unique ID between metadata and deposit
The functionality of zen-do depends on being able to determine whether a given metadata file has a corresponding Zenodo deposit on their servers or not. This is only possible if one local metadata file is clearly and unambiguously connected to one Zenodo deposit on the server.
While Zenodo will create a unique deposit ID once a deposit has been created, that means that the user (or us) would have to create the deposit first and then add the deposit ID to the metadata file. This is not how we want zen-do to behave.
So instead of using the ID created by Zenodo, we define our own ID and list it in the related_identifiers of the metadata. We do not use the repository URL as the ID because we want to be able to create multiple deposits for the same repository, e.g., one for the source code and one for the documentation. We decided on using a URN ID that looks like:
urn:zenodo:<unique-id>:<optional-sub-id>The only required parts are the urn:zenodo prefix and the <unique-id>. But if the user wants to have multiple deposits for the same <unique-id>, they should use the optional <optional-sub-id> to distinguish between those outputs. If the metadata file is hosted on a GitHub repository, we recommend:
urn:zenodo:<github-username>:<repo-name>:<output-type>So if we made a metadata file for the zen-do repository to upload the documentation as a PDF as a deposit, it might look like urn:zenodo:seedcase-project:zen-do:docs. If we wanted to make a deposit for the same repository but for the source code instead, it might look like urn:zenodo:seedcase-project:zen-do:source. The final <output_type> part is used to distinguish between different types of deposits for the same repository and is arbitrary and up to the user to decide on the name.
Because we depend on this URN, all metadata files must have this URN in the related_identifiers field in the .zenodo.toml file. This also means that the user needs to manually add it and manually decide on an ID that is unique enough for their purposes.
Zenodo access token
This is required in order to interact with the Zenodo API. Users can’t directly give zen-do this token. For security purposes, zen-do doesn’t accept the token as an argument since that would be visible in the terminal history and process list. Instead, zen-do will look for a token with the name ZENODO_TOKEN (or ZENODO_SANDBOX_TOKEN) in the system keyring first and, if not found, in the environment variables.
We only allow the use of an environment variable because continuous deployment platforms like GitHub Actions have built-in support for secret environment variables, and this is a common way to store and use secrets in these types of pipelines. Outside of these deployment platforms, we recommend users to store their token in their system keyring, which is a more secure way to store secrets.
Files
These are the files that will be attached to a Zenodo deposit that the metadata is describing. These files will be be uploaded along with the metadata in .zenodo.toml to the Zenodo deposit. Any file that is uploadable to Zenodo is accepted.