README.md

FIWARE Data Models

This repository contains:

• JSON Schemas and documentation on harmonized datamodels for smart cities, developed jointly with OASC, and other domains.
• code that allows to expose different harmonized datasets useful for different applications. Such datasets are exposed through the FIWARE NGSI version 2 API (query).

This work is aligned with the results of the GSMA IoT Big Data Project. Such project is working on the harmonization of APIs and data models for fueling IoT and Big Data Ecosystems. In fact the FIWARE datamodels are a superset of the GSMA Data Models.

All the code in this repository is licensed under the MIT License. However each original data source may have a different license. So before using harmonized data please check carefully each data license.

All the datamodels documented here are offered under a Creative Commons by Attribution 4.0 License.

JSON Schemas

We intend to provide a JSON Schema for every harmonized data model. In the future all the documentation could be generated from a JSON Schema, as it is part of our roadmap. The different JSON Schemas usually depend on common JSON Schema definitions found at the root directory of this repository.

There are different online JSON Schema Validators, for instance: http://jsonschemalint.com/. For the development of these schemas the AJV JSON Schema Validator is being used. For using it just install it through npm:

    npm install ajv
    npm install ajv-cli

A validate.sh script is provided for convenience.

Note: JSON Schemas only capture the NGSI simplified representation, this means that to test the JSON schema examples with a FIWARE NGSI version 2 API implementation, you need to use the keyValues mode (options=keyValues).

How to contribute

Contributions should come in the form of pull requests.

New data models should be added under a folder structured as follows:

• specs/
  • NewModel/
    • doc/
      • spec.md: A data model description based on the data model template, e.g. spec.md of WeatherObserved.
    • README.md: A summary file (as an extract from the spec file), e.g. README.md of WeatherObserved
    • schema.json: The JSON Schema definition, e.g. schema.json of WeatherObserved
    • example.json: One or more JSON example file, e.g. example.json of WeatherObserved

The name of the folder should match the entity type used in the JSON Schema (e.g. NewModel). For data models including more entities, a hierarchical folder should be used. The father folder can include common JSON schemas shared among the entities. e.g.:

• specs/
  • NewModel/
    • doc/
      • spec.md
    • README.md
    • newmodel-schema.json: the common schema for the different entities.
    • NewModelEntityOne/
      • doc/
        • spec.md
      • README.md
      • schema.json
      • example.json
    • NewModelEntityTwo/
      • doc/
        • spec.md
      • README.md
      • schema.json
      • example.json

To facilitate contributions and their validation, we developed a tool that is also used for the Continuous Integration of FIWARE Data Models. The FIWARE Data Model validator checks the adherence of each data model to the FIWARE Data Models guidelines.

For using it just install it through npm:

   npm install -g fiware-model-validator

More details are available in the validator documentation.

Related Projects

See:

• https://github.com/GSMADeveloper/HarmonisedEntityDefinitions
• https://github.com/GSMADeveloper/HarmonisedEntityReferences
• schema.org