Reference data

One of Hermine’s two main purposes is to facilitate Open Source licenses analysis. As a tool it aims at automating the application of this analysis to your SBOMs, as a community it aims at building a common language and understanding of licences and their obligations within Hermine’s user community. This is materialized by Hermine Community Data, which is built on Hermine-data repository.

The reference Data is to display this community data and allow you to manage the interactions between your data and community data.

Hermine Reference Data is made of 2 top-level types of object :

  • Licences

  • Compliance actions

Generic principles

The community data is stored as individual json files in their respective directories (generics and licences) on Hermine-data repository.

For licences, the files are names {SPDX ID}.json.

For generics, the title of the obligation is used and filtered to be suitable for a file name (no special characters, no spaces, etc.) : {Filtered title}.json.

This allow to easily follow the changes to the objects and have readable diffs, leveraging the native capabilities of git and its tooling ecosystem.

For each release of the data, a global shared.json file, containing all the licences and generics obligations, is generated by the to_dist.py script, which is launched by the Gitlab CI.

Importing Community Data into your Hermine Server

  1. Get the latest release of the data : https://gitlab.com/hermine-project/community-data/-/releases/permalink/latest/downloads/shared.json

  2. Import it in your instance

    Because reference data is cached at runtime, you will have to restart your server after importing reference data.

If you have installed Hermine manually 
# in your poetry environment
python hermine/manage.py init_shared_data /path/to/shared.json

If you have installed Hermine via docker compose
Copy the `shared.json` file in the `docker` folder of the Hermine code and rebuild your image.

Interacting with reference data in your Hermine instance

Summary of reference data

Once you have imported reference data, if your user has the appropriate rights, you will have a new Shared reference data menu entry in the Legal section, leading to the /shared/ page, that presents a summary of the differences between local and reference data.

In the licences and generics pages

In the licences and generics pages, a column Differences  with reference shows the status of each licence ; values can be Local only,No differences or See differences with a link to the page showing the differences.

Page showing the differences

The page lists the differences, showing local and reference value, with a button to update your local value.

In the licence and compliance action pages

In each licence or compliance action page, if the licence or compliance action identifier is present in the reference data, a information box will be displayed if the local data for this object differs from the one in Reference Data, with a link to display the differences.