# Introduction and Nomenclature
Here the different terms used throughout the library are being explained.
In general there are three main terms defined below. 

**General knowledgeof the [FIWARE](https://www.fiware.org/) architecture and NGSIv2 is assumed!**

## Data Model
A data model is a general representation of a certain kind of object or 
abstract concept. Mostly devices like sensors and actuators are modeled, but more 
abstract objects like a state machine are possible as well. The data model
defines which values and attributes are associated with an object of a 
certain type! 

FIWARE (NGSIv2) defines two different formats to express
entities and devices. One is the key-value representation and one is the 
normalized format, with the latter being the more detailed on!

## DataModel-Class
Each of the different ways to write down an entity is implemented in a backend
class that. These classes all inherit from 
[DataModel](./fidere.api.models.md#base-datamodel), which defines
the necessary functions!
Currently, there is an implementation for the [normalized format](fidere.normalized_model)

## JSON-Schema
The schema is the `*.json` file that holds the information about the data
model in the JSON-Schema format. The according specification can be found
[here](https://json-schema.org/specification.html). The exact convention
for modeling an entity as JSON-Schema is dependent on the according backend
DataModel implementation. Mainly the normalized model or key-value model.

## Instance
An instance is a specific version of a device or an entity. It should be
based on a certain data model and is **ALWAYS in key-value format**, no 
matter which DataModel was used as backend. It must
have values for all mandatory fields for devices and entities as defined
in the fiware specification. The instance in always expected to be a `dict`
or a compatible data type.

Let us make an example!
A data model for a certain sensor was defined. Now with the instance we
can define a specific sensor based on this data model. An entity instance
could look like

```json
{
    "id": "TemperatureSensor:001",
    "type": "Sensor",
    "manufacturer": "CompanyABC",
    "refLocation": "Building:001"
}
```

Here `id` and `type` are mandatory fields, and using an instance
without these fields will result in an exception being raised! Any values
for fields defined in the schema and not supplied in the instance will be
filled with its default value!

## Device and Entity
With Device and Entity or sometimes named ContextEntity we mean
the class objects from the [FiLiP](https://github.com/RWTH-EBC/FiLiP) library.

Usually either an Entity or Device results when an instance is combined with
the according parsed JSON-Schema data model. Thanks to the `IoTA-Client`
and `ContextBrokerClient` from `FiLiP` it is easy to work around the FIWARE APIs.

