# ESCAPE metadata template

Among the [OSSR guidelines and rules of participation](
https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/contribute_ossr/) - agreed between the ESCAPE WP3 participants -, 
we **strongly recommend** to include a metadata descriptive file into the entry to be uploaded to the ESCAPE repository.

In the ESCAPE context, the use of the [CodeMeta schema](https://codemeta.github.io/) is strongly advised for uploads containing software. 
However, we support and encourage the use of any other metadata standard. If this is the case, please contact us 
(see just below). However, please note that the GitLab-Zenodo connection only supports - at the moment - codemeta metadata
 descriptive files.  

Any comments are more than welcome. Open an issue or contact us [via email](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).

## Quickstart - How to incorporate a CodeMeta metadata file into your project.

 1. Go to the [CodeMeta generator](https://codemeta.github.io/codemeta-generator/). Generate a `codemeta.json` file based on your project.
    - Check - in the same web application - that the generated file is valid !  
 2. Copy the generated metadata into a `codemeta.json` file and include it in the **root directory** of your project.
 3. Please **pay attention to the `keywords` field**. Include **at least one** of the following keywords **per category**; 
 besides all the keywords that you would like to attach to your project.   

### Keywords list

In your `codemeta.json` file **add, at least,** one keywords of the following **three** categories:

Multiple keywords must be separated with a comma `,` and between double `"`;
```json
 {
   ...
 "keywords": ["CTA", "Astroparticle physics", "jupyter-notebook", ...],
   ...  
}
```

1. Project category:
    - CTA
    - LSST
    - LOFAR
    - SKA
    - EGO-Virgo
    - KM3NeT
    - ELT
    - EST
    - HL-LHC
    - FAIR
    - CERN
    - ESO
    - JIVE
    - VO
    - EOSC
    - ESO
2. Domain category (single keywords):
    - `Astronomy`
    - `Astroparticle physics`
    - `Particle physics`
3. Notebooks category. At the moment only Jupyter notebooks are supported.
    - Add `jupyter-notebook` as keyword if you project is based on or contains jupyter notebooks
    - Do not add anything otherwise
 
 
The reason to add the above keywords is just for classification and findability purposes in the OSSR (the
 [ESCAPE2020 Zenodo community](https://zenodo.org/communities/escape2020) by other services such as the ESFRI Science Analysis Platform.
 
## Create a Zenodo metadata file from the a CodeMeta schema file

The zenodo repository does not accept codemeta metadata files yet. Meanwhile, the [codemeta2zenodo library](https://gitlab.in2p3.fr/escape2020/wp3/codemeta2zenodo) 
provides a simple tool to create a native Zenodo metadata file (`.zenodo.json`) from a `codemeta.json` file. To do so;

 1. Include a `codemeta.json` file to the root directory of your project.
 2. Install the `codemeta2zenodo` package;
```bash
 $ git clone https://gitlab.in2p3.fr/escape2020/wp3/codemeta2zenodo.git
 $ cd codemeta2zenodo
 $ pip install .
```
 3. And then just run
 ```bash
 $ codemeta2zenodo --codemeta_file codemeta.json
```

Also, you can check and use the [**online codemeta2zenodo**](https://escape2020.pages.in2p3.fr/wp3/codemeta2zenodo/codemeta2zenodo.html)
converter, based in the same library.

In case of doubts or problems, please [contact us](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).


**THIS STAGE IS RECOMMENDED, BUT NOT COMPULSORY FOR THE OSSR ONBOARDING.** 
 - If you have linked your GitLab project with Zenodo using the autonomous procedure that [we propose](
 https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_in_repository/), this stage will be done automatically. 
 - If you are providing software via GitHub - and/or its [autonomous procedure](https://guides.github.com/activities/citable-code/) -, 
 this stage is not mandatory (but still recommended). GitHub will take care of fetching the metadata from the project directly. 

## Metadata schema templates

Inside the `codemeta_utils` directory you will find two template files with **the all the properties (terms) of the corresponding metadata schema context** 
 for both the CodeMeta metadata file and the Zenodo metadata file.
 
Feel free to create and incorporate the metadata files starting from these templates. However, please note that  
the final filenames **MUST** be either `codemeta.json` or `.zenodo.json` (note the `.` !). In case you do not fill or 
write nothing on any dictionary key field, take it out of the file.

In case of doubts please also check;
  - The [CodeMeta properties/terms description](https://codemeta.github.io/terms/) or,
  - the [`metadata representation`](https://developers.zenodo.org/#representation) allowed for the `.zenodo.json` metadata file.
  
  
### Extending the CodeMeta Context schema

In case you find that CodeMeta context does not describe deep enough your digital resource, you can extend the metadata 
context and combine it with all the terms available at [https://schema.org](https://schema.org/docs/full.html).
For this purpose, and following the [CodeMeta's developer guide](https://codemeta.github.io/developer-guide/);

   1. Modify the `"@Context"` key of the `codemeta.json` as; 
    
    "@context": ["https://raw.githubusercontent.com/codemeta/codemeta/2.0-rc/codemeta.jsonld", "http://schema.org/"]
     
   2. Include the desired terms / properties following the `schema.org` context.
   3. Contact us for a likely implementation into the OSSR environment ;-)


-----------------
-----------------


### How to automatise the upload of a GitLab project to Zenodo via the GitLab-CI

 - Add a `codemeta.js` file to your repository.
 - Link your GitLab project and your Zenodo accounts.
 - Add the following code snippet (Section 3. of the detailed tutorial) to the `.gitlab-ci.yml` file of your project and let the pipeline work !
 - Check the [detailed tutorial](https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_tutorial/) for more details.