Structure of the `jsonnetfile.json` file

This article is part 2 of the articles about dependency management for Jsonnet files and projects.

The series consists of the following parts:

1. Dependency and package management for Jsonnet files (jb tool).
2. The Structure and the purpose of the jsonnetfile.json file
3. Transitive dependencies, legacy imports, local vs. remote dependencies

What is it #

The jsonnetfile.json file is a configuration file used in conjunction with the Jsonnet-Bundler (or jb) tool. It is used to specify the dependencies and their versions for a Jsonnet project.

Jsonnet is a data templating language that allows you to define complex JSON structures using a concise and flexible syntax. When working on Jsonnet projects, it is common to have dependencies on external libraries or shared code. The jsonnetfile.json file helps manage these dependencies and ensures reproducibility and consistency across different environments.

The jsonnetfile.json file typically resides in the root directory of your Jsonnet project. It specifies the list of dependencies your project relies on, along with their versions.

The jb tool uses this file to fetch the specified dependencies and make them available for your project.

What is inside the file? #

Here is an example structure of a jsonnetfile.json file:

{
  "version": 1,
  "dependencies": [
    {
      "source": {
        "git": {
          "remote": "https://github.com/grafana/grafonnet-lib",
          "subdir": "/grafonnet"
        }
      },
      "name": "grafonnet-lib",
      "version": "master"
    },
    {
      "source": {
        "local": {
          "directory": "./local-directory"
        }
      },
      "name": "another-lib",
      "version": "v2.1.0"
    }
  ]
}

Let’s break down the structure:

• “version”: This specifies the version of the jsonnetfile.json file format. Currently, the supported version is 1.

  • “dependencies”: This is an array that contains the list of dependencies for the project.

    • Each dependency is represented as an object with the following properties:

      • “source”: This specifies the source of the dependency, which can be a Git repository or a local directory.

        • If the source is a Git repository, it is defined as follows:

          • “git”: This object specifies the Git-related information.

            • “remote”: This is the URL of the Git repository.

            • “subdir”: This is the specific directory to fetch.

        • If the source is a local directory, it is defined as follows:

        • “local”: This object specifies the local directory path as the source.

          • directory: A local directory where the source code is stored.

      • “name”: This is the name of the dependency.

      • “version”: This is the version or release tag of the dependency to use.

The jsonnetfile.json file is used by the jb tool to fetch the specified dependencies and resolve their versions, ensuring reproducibility and consistency in a Jsonnet project.

How to start a project using jsonnet-bundler tool ? #

To create an empty project with the jsonnetfile.json file, you can follow these steps:

1. Create a new directory for your project. You can choose any name for your project directory.

2. Navigate to the project directory using the command line or your file explorer.

3. Create a new file in the project directory and name it jsonnetfile.json. You can use a text editor or IDE of your choice to create and edit the file.

4. Open the jsonnetfile.json file and add the following content to create an empty jsonnetfile.json file structure:

   {
     "version": 1,
     "dependencies": [],
     "legacyImports": true
   }
   

   This defines an empty jsonnetfile.json file with the required version field set to 1 and an empty array for dependencies.

5. Save the jsonnetfile.json file.

6. Or you can initialize an empty project using the following commands:

    $ mkdir myproject
    $ cd myproject
    $ jb init
   

   The commands will create an empty folder and initialize the project with default settings.

At this point, you have created an empty project directory with the jsonnetfile.json file.

You can now add your Jsonnet code files, specify the dependencies, and fill in the jsonnetfile.json file with the required dependencies and their versions as your project progresses.

How to add dependencies? #

Now you have an empty project, and it’s time to add dependencies to it.

The existence of the jsonnetfile.json file means your directory is now a jsonnet-bundler package that can define dependencies.

To add a dependency to the jsonnetfile.json file, you can follow these steps:

• Open the jsonnetfile.json file in a text editor or IDE. Make sure you are in the project directory where the file is located.

• Locate the “dependencies” array in the jsonnetfile.json file.

• Add a new object to the “dependencies” array, representing the dependency you want to add. The object should include the following properties:

  • “source”: Specify the source of the dependency, such as a Git repository or a local directory. This is defined as an object with specific properties based on the source type.

    1. If the source is a Git repository, use the following structure:

          "source": {
            "git": {
              "remote": "<repository URL>",
              "version": "<version or commit>"
            }
          }
    

    Replace with the URL of the Git repository, and with the desired version, commit hash (SHA-1), or tag of the repository.

    2. If the source is a local directory, use the following structure:

       "source": {
         "local": {
           "directory": "<directory path>"
         }
       }
    

    Replace with the path to the local directory containing the dependency.

  • “name”: Provide a name for the dependency.

  • “version”: Specify the desired version or release tag of the dependency.

• Save the file.

Here’s an example of adding a dependency to the jsonnetfile.json file:

{
  "version": 1,
  "dependencies": [
    {
      "source": {
        "git": {
          "remote": "https://github.com/anguslees/kustomize-libsonnet.git",
          "subdir": ""
        }
      },
      "version": "master"
    }
  ],
  "legacyImports": true
}

After adding the dependency to the jsonnetfile.json file, you can use the Jsonnet-Bundler (jb) tool to fetch the dependency and make it available for your project.

Run the jb install or jb update commands to ensure the dependency is resolved and included in your Jsonnet project.