fidere 1.0.1

My package description

About this project

The FiDERe (FIWARE Datamodel (based) Entity Rendering) 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
• How To Use
  • Installation
  • Documentation
  • How it works
• Tests
• Contribute to the parser
• Contributors

How To Use

Installation

There are several ways for installing FiDERe.

First is the installation from the jugit package registry.

pip install fidere

Alternatively a local installation using

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 section for more information on tests.
2. Docs: pip install fidere[doc] used for building the documentation locally using sphinx-versioned

Overview

Overall the parser is a relatively simple tool so, the 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 to parse JSON-Schema files into pydantic classes for data validation.
2. is 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. 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 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 before running

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, [e-mail])