This repository contains a set of OASC Shared Data Models for Smart City domains, adopted and developed in the SynchroniCity project. These data models are one of the "Interoperability Points" of the SynchroniCity framework and are a concrete extension of the OASC Minimal Interoperability Mechanisms (MIMs). In particular the repository contains: JSON Schemas and documentation on harmonized datamodels for smart cities, developed jointly with OASC, and other domains. Such datasets are exposed through the SynchroniCity Context Management API based on FIWARE NGSI version 2 API (query). The Data Models have also been expressed using the ETSI standard NGSI-LD. There is a guide to guide SynchroniCity partners in the usage of NGSI-LD.
The baseline of the OASC SynchroniCity data models is the FIWARE Data Models catalogue developed by the FIWARE community. Also SynchroniCity project has analysed:
- The IoT Big Data Harmonised Data Models developed by GSMA.
- The schema.org Data Models developed by the Browser and search engine communities
- Ontologies promoted by the European standards community, particularly SAREF.
Some modifications to the original data models have been performed in order to extend them to fit SynchroniCity cities requirements. Also, completelly new data models have been created to cover specific needs. The data model development is an going process, so please refer to this website for the last version of the SynchroniCity 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.
The following table shows the list of SynchroniCity data models. For each one is also defined the approval status:
- Approved: the data model has been officialy adopted by SynchroniCity and used by the Reference Zones (Cities) of the project
- Under Discussion: the data model is under discussion: SynchroniCity partners and external stakeholders can suggest changes or extensions. The data model could be used but cannot be considered stable.
| Vertical | Data Model | Description | Original Source | Approval Status |
|---|---|---|---|---|
| Environment | AirQualityObserved | It represents an observation of air quality conditions at a certain place and time | GSMA | Approved |
| Environment | NoiseLevelObserved | It represents an observation of those parameters that estimate noise pressure levels at a certain place and time | FIWARE | Approved |
| PointOfInterest | PointOfInterest | A harmonised geographic description of a Point of Interest | GSMA updated by SynchroniCity | Approved |
| PointOfInterest | Beach | A harmonised geographic description of a beach | FIWARE | Approved |
| PointOfInterest | Museum | A harmonised geographic description of a museum | FIWARE | Approved |
| PointOfInterest | Store | A harmonised geographic description of a store | Developed by SynchroniCity | Approved |
| Transportation | BikeHireDockingStation | A bike hire docking station where subscribed users can hire and return a bike. | FIWARE | Approved |
| Transportation | TrafficFlowObserved | An observation of traffic flow conditions at a certain place and time. | FIWARE | Approved |
| Transportation | EVChargingStation | A public charging station supplying energy to electrical vehicles. | Developed by SynchroniCity | Approved |
| Transportation | CrowdFlowObserved | An observation of people movement at a certain place and time. | Developed by Synchronicity | Approved |
| Transportation | Vehicle | Real time tracking of the vehicles that are used for public transportation (buses, trains, etc.) | FIWARE | Approved |
| Transportation | CarSharingStation | A site dedicated to car sharing with either direct access from a road or with suitable and clearly marked access points. | Developed by SynchroniCity | Approved |
| Transportation | RestrictedTrafficArea | An area of a city in which the traffic generated by cars or any other kind of vehicles is subjected to limitation. | Developed by SynchroniCity | Approved |
| Transportation | Road | A harmonised geographic and contextual description of a road. Roads are made up of one or more RoadSegment entities. | FIWARE | Approved |
| Transportation | RoadSegment | A harmonised geographic and contextual description of a road segment. A collection of road segments are used to describe a Road. | FIWARE | Approved |
| Transportation | RoadAccident | It describes road accidents giving description and information about causes, casualties and aftermath. | Developed by SynchroniCity | Approved |
| Weather | WeatherObserved | An observation of weather conditions at a certain place and time. | GSMA - Extended by FIWARE | Approved |
| Weather | WeatherForecast | Harmonised description of a Weather Forecast. | GSMA - Extended by FIWARE | Approved |
| Urban Mobility | GtfsAgency | See https://developers.google.com/transit/gtfs/reference/#agencytxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsStop | See https://developers.google.com/transit/gtfs/reference/#agencytxtSee https://developers.google.com/transit/gtfs/reference/#stopstxt It represents a GTFS stop which location_type shall be equal to 0. | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsStation | See https://developers.google.com/transit/gtfs/reference/#stopstxt It is a GTFS stop which location_type is equal to 1. | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsAccessPoint | See https://developers.google.com/transit/gtfs/reference/#stopstxt It is a GTFS stop which location_type is equal to 2. | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsRoute | See https://developers.google.com/transit/gtfs/reference/#routestxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsTrip | See https://developers.google.com/transit/gtfs/reference/#tripstxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsShape | See https://developers.google.com/transit/gtfs/reference/#shapestxt It represents a GTFS shape. | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsStopTime | See https://developers.google.com/transit/gtfs/reference/#stop_timestxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsService | It represents a transportation service which is available for one or more routes at certain dates. | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsCalendarRule | See https://developers.google.com/transit/gtfs/reference/#calendartxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsCalendarDateRule | See https://developers.google.com/transit/gtfs/reference/#calendar_datestxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsFrequency | See https://developers.google.com/transit/gtfs/reference/#frequenciestxt | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsTransferRule | See https://developers.google.com/transit/gtfs/reference/#transferstxt | Developed by SynchroniCity | Approved |
| Urban Mobility | ArrivalEstimation | It captures the estimated arrival time of a public transport vehicle reaching a particular stop, whilst the vehicle is servicing a particular route. | Developed by SynchroniCity | Approved |
| Urban Mobility | GtfsTransitFeedFile | Provides the Location (URL) of the ZIP file containing a valid GTFS transit feed. | Developed by SynchroniCity | Approved |
| Urban Mobility | PublicTransportRoute | Provides generic model for public transport route. | Developed by SynchroniCity | Approved |
| Urban Mobility | PublicTransportStop | Provides generic model for public transport stop. | Developed by SynchroniCity | Approved |
| Events | Event | Events happening in the city | schema.org | Under discussion |
| Parking | ParkingSpot | An individual, usually monitored, parking spot/parking lot | FIWARE | Approved |
| Parking | OffStreetParking | An offstreet parking site with explicit entries and exits | FIWARE | Approved |
| Parking | OnStreetParking | An on street, free entry (but might be metered) parking zone which contains at least one or more adjacent parking spots | FIWARE | Approved |
| Parking | ParkingGroup | A group of parking spots. | FIWARE | Approved |
| Parks & Gardens | Garden | A distinguishable planned space, usually outdoors, set aside for the display, cultivation, and enjoyment of plants and other forms of nature. | FIWARE | Approved |
| Parks & Gardens | GreenspaceRecord | Harmonised description of the conditions recorded on a particular area or point inside a greenspace (flower bed, garden, etc.) | FIWARE | Approved |
| Waste Management | WasteContainer | Waste Containers | FIWARE | Approved |
| Waste Management | WasteContainerModel | Static properties of a waste container (big belly) | FIWARE | Approved |
| Waste Measurement | WasteMeasurement | A waste measurement | Developed by SynchroniCity | Under discussion |
| Device | Device | An apparatus (hardware + software + firmware) intended to accomplish a particular task (sensing the environment, actuating, etc.). | FIWARE | Approved |
| Device | DeviceModel | This entity captures the static properties of a Device. | FIWARE | Approved |
| QueueMonitor | QueueMonitor | This data model describes a single queue line for a single service provided by an office. | Developed by SynchroniCity | Approved |
| Energy | ThreePhaseMultiCircuitAcMeasurement | Represents a measurement from an electrical sub-metering system that monitors three-phase alternating current across multiple circuits. | Developed by SynchroniCity | Approved |
| Energy | GreenEnergyGenerator | Generic model for Green Energy Generator. A device which can generate energy using Solar or Eolic green energy. | Developed by SynchroniCity | Approved |
| Energy | GreenEnergyMeasurement | Generic model for a snapshot measure of energy generated using one or more green energy sources. Thus, an entity of type GreenEnergyMeasurement cannot exist without an accompanying Entity of Type GreenEnergyGenerator | Developed by SynchroniCity | Approved |
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).
SynchroniCity provides a set of guidelines for defining new data models. Further information can be found in SynchroniCity Deliverable D2.2
Despite the Entity ID within any existing Context Entity is originally free text, NGSI API provides several features based on this parameter to assist NGSI operations. The following recommendations, which are not mandatory to be SynchroniCity compliant, represents a set of good practices to define entity IDs that improves the context queries, subscritions and discovery actions.
These guidelines are based on the incoming NGSI-LD standard and are used by several SynchoniCity Reference Zones' instances. According to them, the Entity ID would be a text string composed by several fields separated by colons.
-
Three first fields represent the NGSI-LD standard and identifies the entity as a NGSI-LD compliant entity:
-
urnis always set to "urn" and identies the entity ID as an urn. -
ngsi-ldrepresents an ngsi-ld entity when set to "ngsi-ld". -
entity-Typematches the type attribute of the entity. -
Next optional fields are proposed by SynchroniCity and are arranged to organise the entities according their deployment and functionaly:
- site can represent a RZ, City or area that includes several different IoT deployments, services or apps (e.g., Porto, Milano, Santander, Aarhus, Andorra ... ).
- service represents a smart city service/application domain, for example parking, waste management, environmental etc.
- group can be used for grouping assets under the same service and/or provider (so it can be used to identify different IoT providers). It is responsibility of OS sites to maintain proper group keys.
- entityName The Entity / Device identifier which should be unique at the corresponding site, service and group.
Entities’ ID definition
urn |
ngsi-ld |
entity-Type |
site | service | group | entityName |
|---|---|---|---|---|---|---|
| urn | ngsi-ld | OnStreetParking | santander | parking | onStreet | StaLuciaEast |
| urn | ngsi-ld | ParkingSpot | santander | parking | parkingSpot | 3601 |
| urn | ngsi-ld | TrafficFlowObserved | santander | traffic | TrafficFlowObserved | 1001 |
Entity IDs examples
"urn:ngsi-ld:OnStreetParking:santander:parking:onStreet:StaLuciaEast"
"urn:ngsi-ld:ParkingSpot:santander:parking:parkingSpot:3601"
"urn:ngsi-ld:TrafficFlowObserved:santander:traffic:TrafficFlowObserved:1001"
Contributions should come in the form of pull requests.
New data models should be added under a folder structured as follows:
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 WeatherObservedschema.json: The JSON Schema definition, e.g. schema.json of WeatherObservedexample.json: One or more JSON example file, e.g. example.json of WeatherObservedexample-normalized.json: One or more JSON example file in NGSI v2 normalized format, e.g. example-normalized.json of WeatherObservedexample-normalized-ld.jsonld: One or more JSON example file in NGSI-LD normalized format, e.g. example-normalized-ld.jsonld 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.:
NewModel/doc/spec.md
README.mdnewmodel-schema.json: the common schema for the different entities.NewModelEntityOne/doc/spec.md
README.mdschema.jsonexample.jsonexample-normalized.jsonexample-normalized-ld.jsonld
NewModelEntityTwo/doc/spec.md
README.mdschema.jsonexample.jsonexample-normalized.jsonexample-normalized-ld.jsonld
SynchroniCity developed a tool to validate the data models. Code and documentation can be found here: https://gitlab.com/synchronicity-iot/rz-instance-validator
See: