At the core of Sprout is the Data Package, which is a standardized way of documenting data via structured metadata. Technically, a Data Package is any folder that has a file called datapackage.json in it that contains metadata following the formal Data Package specification.
The metadata in datapackage.json can describe both the Data Package (e.g. its title, creation data, and contributors) and any data included in the Data Package (e.g. the name, data type, and description of each column/variable in the data). This metadata is stored in JSON format with a standardized naming convention, e.g. the title of the project should be stored as "title": "your project title".
In this guide, we will refer to each piece of metadata stored in the JSON file as a metadata property (or just a property for short). You can view an example of a complete datapackage.json file in this example repository.
The Data Package standard provides a standardised structure and naming scheme in datapackage.json. This has many advantages in terms of reproducibility and machine-readability, but it also makes it difficult to manually create the datapackage.json file and remember all the names for each of the different properties. Manually editing this file is also ill-advised since you are more likely to accidentally make typos or accidentally not follow the schema provided by the specification. To make this process more convenient and robust, Sprout provides a way to create and edit the metadata in datapackage.json programmatically via Python scripts.
Let’s start by taking a look at what your project’s file structure should look like after following the installation section of this guide:
Sprout assumes the working directory is the root of your Python project—where your .git/ folder and/or pyproject.toml file are located. If you used our Data Package template as we recommend in the installation guide, you will see additional config files to the ones listed above.
Sprout also assumes that the Python project is structured as a src/ layout Python package.
Since there is no datapackage.json file in our root folder, we can’t yet call it a Data Package. To create the Python script that contains the package metadata, we can use the init-metadata CLI command:
This will create a Python file in the newly created src/diabetes_study/metadata/ directory of your data package.
The file structure should now look like:
Inside the newly created package.py file, you will find a template for more easily creating the metadata properties of your data package. We will walk through the full template in more detail in the next section of the guide. Here, we will first start with a simplified package.py script to more easily understand how to manage metadata via this script.
Sprout uses Python classes to support creating and editing metadata. For example, through the SproutProperties class you can use tab completion to view the names of all existing metadata properties instead of trying to memorize them or looking them up in the documentation each time. The docstring of each class has more information on what to write in the metadata. This documentation is available both in your IDE and this website, e.g. for SproutProperties.
In the example below, we have filled out all the required metadata properties on the package level with sample values. You can go ahead and copy this over to your package.py replacing any existing code there.
src/diabetes_study/metadata/package.py
import seedcase_sprout as sp
package_properties = sp.SproutProperties(
name="diabetes-study",
title="A Study on Diabetes",
description="Data from a 2021 study on diabetes prevalence",
licenses=[
sp.LicenseProperties(
name="ODC-BY-1.0",
),
],
## Autogenerated:
id="c0f9b217-589b-4ee4-a917-3c4f21e3be8d",
version="0.1.0",
created="2025-11-05T16:16:20+01:00",
)datapackage.jsonNow that you’ve filled in some of the package metadata, it’s time to create your datapackage.json file. Creating this file also officially makes this Python project a Data Package. You can use the write_properties() function for this by including it within some type of script, like build.py script (see our template for more details):
Then, use uv to run the script from the Terminal:
The write_properties() function will give an error if the SproutProperties object is missing some of its required fields or if they are not filled in correctly. In that case, a datapackage.json file won’t be created. So you will have to return to the package.py file and fill in the correct properties.
The write_properties() function created the datapackage.json file in your data package’s diabetes-study root folder, which contains the properties you added to it. Now, you will see the added datapackage.json file in your Data Package folder.
The content of this file should look like this:
datapackage.json
Congratulations, you’ve created your first Data Package! Remember that you will never need to edit the datapackage.json file manually. Instead, you’ll edit package.py and run build.py to update datapackage.json.