# About this project

The **FiDERe** (**FI**WARE **Datamodel** (based) **Entity** **R**endering) 
library is a tool for working with JSON schema 
data models around the FIWARE architecture.

Although there are already JSON schema data models that are maintained by the FIWARE 
Association, the following problems occur:
* The models have many unneeded attributes 
* Are only suitable for use with the context broker
* Do not allow definition of attribute metadata 
* The data models are often deeply nested with references

To address these problems, we at ICE-1 have intensively studied
the concept of data modelling, data validation and also the parsing of 
these models and data around the FIWARE platform. One result 
of this work is the **FiDERe**.

The aim of the library is to provide a simple way of working with 
predefined data models in JSON schema format to create validated objects 
which can be used on the FIWARE IoT Agent JSON in the form of devices or as 
entities on the Orion Context Broker.

# Table of Contents
* [Table of Contents](#table-of-contents)
* [How To Use](#how-to-use)
   + [Installation](#installation)
   + [Documentation](#documentation)
   + [How it works](#how-it-works)
* [Tests](#tests)
* [Contribute to the parser](#contribute-to-the-parser)
* [Contributors](#contributors)

# How To Use
## Installation

There are several ways for installing FiDERe.

First is the installation from the jugit package registry.
```shell
pip install fidere
```

Alternatively a local installation using
```shell
git clone https://jugit.fz-juelich.de/iek-10/public/ict-platform/fiware-applications/fidere.git
git install /path/to/fidere fidere
```

There are two optional components when running installation:
1. **Tests**: `pip install fidere[tests]` used for running tests 
using pytest locally. See [tests](#tests) section for more information on tests.
2. **Docs**: `pip install fidere[doc]` used for building the documentation locally using [sphinx-versioned](https://pypi.org/project/sphinx-versioned-docs/)

## Overview
Overall the parser is a relatively simple tool so, the [examples](examples/). 
If you are just interested in creating your own data models and using FiDERe 
with it, the examples should cover everything you need 
to know. 

There are examples for both JSON-Schemas, instances and the usage of the parser itself.

When working with the parser, you define three different inputs:
1. A JSON-Schema for the object you want to describe. 
There can be different formats when defining JSON Schemas (e.g. Normalized Format)
2. An Identifier (basically a `string`) that is used to uniquely identify 
a parsed JSON-Schema
3. One or more specific instances of the device/entity from the schema 
in key-value format

## How it works
FiDERe is divided into a front facing API the `JsonSchemaParser` itself and a
back facing one as `DataModel` which is taking care of parsing the specific 
JSON-Schema in the background. Each specific way of modelling entities and 
devices in FIWARE like the normalized format or the key-value format. 
Basically when working with the parser you tell it which JSON-Schema file to parse,
the identifier it should use to reference it and which Backend `DataModel` 
to use for parsing.

The parser utilizes two main libraries. 
1. is the 
[datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator) 
to parse JSON-Schema files into pydantic classes for data validation.
2. is [FiLiP](https://github.com/RWTH-EBC/FiLiP), a powerful library
serving as wrapper to the FIWARE REST APIs, making handling entities and 
devices much simpler.

## Documentation
In addition to all the explanations above you can find more detailed documentation 
in [docs](docs/source/index).
There you find some more details on: 
1. How FiDERe works in the background
2. Explanation for different nomenclatur used throughout the FIWARE 
cosmos and more importantly around FiDERe
3. Detailed code documentation (generated from code) for the library

If at any point you want to contribute and implement a new form of data 
model yourself, this is a good place to start reading into the library.


## Tests
Tests are implemented using [pytest](https://docs.pytest.org/en/stable/) 
and currently cover most of the parser's functionality. 
The tests are executed on each commit and span the python version 
**3.9 <= python version <= 3.12**.

Running tests locally requires installation of the according optional 
dependencies as described in the [installation](###installtion) before running
```shell
pytest --no-summary
```
The tests can both be run from the root directory `./` or from `./tests/`.

# Contribute
**FiDERe** is an ever evolving tool all around working with 
devices and entities in the FIWARE architecture. Meaning, there is always 
something to do, change and improve.
The easiest way for you to contribute to this is by raising an issue. 
If you find any missing functionality or a bug, just open up an issue 
and fill in as much information as you can to describe your wanted 
functionality or the problem you are encountering!

An even better way to contribute to the parser is via directly implementing 
said fixes or feature yourself! 
Just open an issue, checkout the branch that is created (manually at the moment), 
implement a feature and create a merge request.

## Contributors

* Sascha Johnen (Forschungszentrum Jülich GmbH. ICE-1, <sa.johnen@fz-juelich.de>)

