<!---  
SPDX-FileCopyrightText: Hermine team <hermine@inno3.fr> 
SPDX-License-Identifier: CC-BY-4.0
-->

# 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](https://gitlab.com/hermine-project/hermine-data).

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
- Generic obligations


## Generic principles

The community data is stored as individual json files in their respective 
directories (`generics` and `licences`) on [Hermine-data repository](https://gitlab.com/hermine-project/hermine-data).
 
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.

<details><summary>If you have installed Hermine manually</summary>
    
```
# in your poetry environment
python hermine/manage.py init_shared_data /path/to/shared.json
```
</details>
<br/>

<details><summary>If you have installed Hermine via docker compose</summary>

<br/>
Copy the `shared.json` file in the `docker` folder of the Hermine code and rebuild your image.

</details>
<br/>
     

## 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 generic obligation pages

In each licence or generic obligation page, if the licence 
or generic obligation 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.