FIWARE Global Summit - FIWARE Context Information Management

Context Information Management with
FIWARE
José Manuel Cantera Fonseca (@jmcantera)
Senior Expert - Technical Lead & Architect
FIWARE Foundation e.V.
May 2018 (Aligned with ETSI ISG CIM)

2
Digitization is starting to gravitate around context information.
Information and its context which describes what is going on,
where, when, why …

3
Tractor
• Location
• Speed
• Direction
Crop
• Humidity
• Leaf area
• Age
Drone
• Location
• Battery level
• Speed
• Direction
… but also
in Agrifood
… not only in
cities

4
Tanker
• Driver
• Location
• Max Volume
• Current Level
• Speed
• Direction
Gas Tank
• Station
• Max Volume
• Current Level
• Min Threshold
• Temperature
Station
• Location
• Owner
• SLA
… but also
in Industry /
Energy
… not only in
cities

FIWARE: Driving the standard for Context Information Management
§ FIWARE NGSI is a simple yet powerful open, royalty-free standard API for Context
Information Management à Published as ETSI Specification
§ A RESTful API using JSON so any web/backend developer gets quickly used to it
§ Yet powerful: FIWARE NGSI supports geo-queries and Linked Data (JSON-LD)
5
Application/Service
Bus
• Location
• No. passengers
• Driver
• Licence plate
Parking
• name
• totalSpotNumber
• availableSpotNumber
• location
• floorNumber
Shop
• Location
• Business name
• Franchise
• Offerings
Context Information
FIWARE NGSI API
Context Information might come from
different sources not only IoT

7
Context Information Management Architectures (I)
Centralized Distributed

8
Context Information Management Architectures (II)
Federated

11
Information Model - Highlights
§ NGSI Entity à Physical or virtual object.
§ It has (one) Entity Type.
§ Uniquely identified by an Entity Id (URI)
§ Entity has zero or more attributes identified by a name
§ Property --> Static or dynamic characteristic of an entity
§ GeoProperty (geospatial context)
§ TemporalProperty (time context)
§ Relationship à Association with a Linked entity (unidirectional)
§ Properties have a value
§ An NGSI value can be a single value (Number, String, boolean), or complex (Array, Structured
Value)
§ Relationships have an object
§ A URI which points to another entity (target of the relationship). Target can be a collection.

12
Information Model – Highlights (II)
§ Cross-Domain, core properties for giving context to your information
§ location à Geospatial location, encoded as GeoJSON.
§ observedAt à Observation timestamp, encoded as ISO8601. (timestamp)
§ createdAt à Creation timestamp (of entity, attribute). dateCreated in Orion
§ modifiedAt à Update timestamp (of entity, attribute). dateModified in Orion
§ unitCode à Units of measurement, encoded as mandated by UN/CEFACT.
§ Recommended practice
§ Use URIs to identify your entities.
§ A URN schema is provided off-the-shelf. It enables to know in advance what entity type
an id refers to
§ urn:ngsi-ld:<Entity_Type_Name>:<Entity_Identification_String>

13
Example
Source: ETSI Specification

15
Classical JSON Representation (a.k.a. Orion / NGSIv2)
{
"id": "urn:ngsi-ld:Vehicle:A4567",
"type": "Vehicle",
"brandName": {
"type": "Property",
"value": "Mercedes"
},
"isParked": {
"type": "Relationship",
"value": "urn:ngsi-ld:OffStreetParking:Downtown1",
"metadata": {
"observedAt": {
"value" : "2017-07-29T12:00:04",
"type" : "DateTime"
},
"providedBy": {
"type" : "Relationship",
"value" : "urn:ngsi-ld:Person:Bob"
}
}
}
}
{
"id": "urn:ngsi-ld:OffStreetParking:Downtown1",
"type": "OffStreetParking",
"availableSpotNumber": {
"type": "Property",
"value": 121,
"metadata" : {
"observedAt": {
"value" : "2017-07-29T12:00:04",
"type" : "DateTime"
},
"reliability": {
"type" : "Property",
"value" : 0.7
},
"providedBy": {
"type" : "Relationship",
"value" : "urn:ngsi-ld:Camera:C1"
}
}
},
"location": {
"type": "geo:json",
"value": {
"type": "Point",
"coordinates": [-8.5, 41.2]
}
}
}

16
Remarks – NGSIv2 representation
§ metadata dictionary allows grouping nested properties and/or nested relationships
§ Should I label attributes using data type names, such as integer, float, etc. or even let
the API implementation to fill them out?
§ Is that really needed? Your runtime already provide JSON member’s data type
§ Exception is “DateTime” for timestamps (Orion implementation needs it)
§ Note: In NGSI-LD “DateTime” is mapped to “TemporalProperty”
§ Should I use other metadata or attribute names different than “location”,
“observedAt”, etc.?
§ We do not recommend it. Please keep your context harmonised!
§ Is it possible to use plain entity identifiers i.e. no URIs?
§ We do not recommend it.
§ Please enable a smooth transition to JSON-LD (NGSI-LD)!!

17
JSON-LD (RDF friendly) representation (a.k.a. NGSI-LD)
{
"type": "Vehicle",
"brandName": {
"type": "Property",
"value": "Mercedes"
},
"isParked": {
"object": "urn:ngsi-ld:OffStreetParking:Downtown1",
"observedAt": "2017-07-29T12:00:04",
"providedBy": {
"object": "urn:ngsi-ld:Person:Bob"
}
},
"@context": [
"http://uri.etsi.org/ngsi-ld/coreContext.jsonld",
"http://example.org/cim/commonTerms.jsonld",
"http://example.org/cim/vehicle.jsonld",
"http://example.org/cim/parking.jsonld"
]
}
{
"availableSpotNumber": {
"type": "Property",
"value": 121,
"observedAt": "2017-07-29T12:05:02",
"reliability": {
"type": "Property",
"value": 0.7
},
"providedBy": {
"object": "urn:ngsi-ld:Camera:C1"
}
},
"location": {
"type": "GeoProperty",
"value": {
"type": "Point",
}
},
"@context": [
]
}

18
Remarks – NGSI-LD vs NGSIv2 (Orion)
§ NGSI-LD: Main syntactical differences with NGSIv2:
§ metadata dictionary no longer needed
§ “object” field to encode relationship target (in order to be compliant with JSON-LD we
cannot overload the “value” field)
§ GeoProperty vs geo:json
§ TemporalProperty vs DateTime
§ included JSON-LD @context à “Unambiguous Semantics”
§ There is a direct mapping between the classical and JSON-LD representation
§ if nested properties and relationships are direct children (only one nesting level)
§ There is a plugin (proxy-wrapper), provided by FIWARE, that can be used to work
directly with JSON-LD representations. See next slides.

19
Remarks – NGSI-LD
§ What is the JSON-LD “@context” member?
§ It provides unambiguous mappings from (local) terms to URIs (fully qualified
names)
§ “Vehicle”: “http://myvocabulary.org/Vehicle”
§ It allows specifying data types for properties outside the main JSON document.
§ Ex. http://schema.org/DateTime
§ In general, you should not worry about it!
§ Provided off-the-shelf by the domain-specific data model designer, ex. Schema.org
§ A default @context will always be implicitly present

20
Simplified representation (keyValues)
{
"name": "Downtown One",
"availableSpotNumber": 121,
"totalSpotNumber": 200,
"location": {
"type": "Point",
},
"@context": [
]
}
Equivalent in NGSI-LD and NGSIv2

Context Information Provision
21

22
HTTP Binding (I)
§ Create Entity
§ POST {apiEndPoint}/entities/
§ 201 Created. Location /entities/{entityId}
§ Delete Entity
§ DELETE {apiEndPoint}/entities/{entityId}
§ 204 No Content
§ 404 if entity does not exist
§ Append new attributes to Entity
§ POST {apiEndPoint}/entities/{entityId}/attrs/
§ 201 Created. 404 if entity does not exist
§ Payload shall contain entity fragment with the new attributes to be appended
§ If attribute already exists, it is overwritten..
Note: In Orion the API endpoint is : /v2

23
HTTP Binding (II)
§ Update Entity Attributes
§ PATCH {apiEndPoint}/entities/{entityId}/attrs/
§ 204 No Content
§ Payload shall contain entity fragment with the new content for attributes
§ Attributes shall already exist. Otherwise 404 error.
§ Delete Entity Attribute
§ DELETE {apiEndPoint}/entities/{entityId}/attrs/{attributeName}
§ 204 No Content
§ 404 if attribute or entity not exist

Context Information Consumption
24

25
HTTP Binding (I)
§ Retrieve Entity by id
§ GET {apiEndPoint}/entities/{entityId}?attrs=<attrList>
§ Returns a JSON object representing the concerned Entity
§ attrs is a list (comma separated) of attributes to be retrieved (each list element can
be a Property or a Relationship name)
§ If attrs is not present then all Entity Attributes will be retrieved
§ Note: In Orion the API endpoint is : /v2

26
HTTP Binding (II)
§ Query Entities
§ GET {apiEndPoint}/entities/?
§ type<typeList>
§ &id=<idList>
§ &idPattern=<RegExp>
§ &q=<Expression>
§ &attrs=<attrList>
§ Lists are comma-separated
§ q accepted expressions
§ <attribute>==<value>, !=, <, <=, >=, pattern matching
§ Use ; to separate terms (logical and)
§ Returns Entity list as a JSON Array. Pagination is available. (limit, offset params)

27
HTTP Binding (III)
§ Geo-query
§ GET {apiEndPoint}/entities/?
§ &georel. Geo-relationship (near, contains, intersects, overlaps, etc.)
§ &geometry. GeoJSON reference geometry (Point, Polygon, etc.)
§ &coordinates. Array of GeoJSON coordinates encoded as string.
§ &coords (Orion Broker). Be careful, order is lat,long (opposite to GeoJSON).
§ Example
§ Give me entities located in a 2km radius of a reference point
§ georel=near;maxDistance==2000&geometry=Point&coordinates=[-4,55] ß ETSI
§ georel=near;maxDistance:2000&geometry=point&coords=55,-4 <– Orion supports this
§ Geo-queries can be combined with content-based filter queries

29
Context Subscription - Description
§ You can subscribe, i.e. ask to receive a notification, to Context Information changes
§ Subscriptions can be on
§ A particular Entity id / set of Entities / Any Entity
§ An Entity Type / set of Entity Types
§ A particular set of watched attributes / Any attribute (of an entity or all entities)
§ Additionally it can be provided
§ A query that must be met by the notified Entities
§ Ex: Only notify when temperature > 20
§ A geoquery that must be met by the notified Entities
§ Ex: Only notify when Entity is located in this area (encoded as a GeoJSON polygon)
§ Notifications are delivered via HTTP POST requests, as a JSON Array of affected Entities,
as per the notification details described by the subscription

30
Context Subscription – JSON Representation
{
"id": "urn:ngsi-ld:Subscription:5aeb0ee97",
"type": "Subscription",
"entities": [
{
"type": "Vehicle"
}
],
"watchedAttributes": ["speed"],
"q": "speed>50",
"geoQ": {
"georel": "near;maxDistance==2000",
"geometry": "Point",
"coordinates": [-1,100]
},
"notification": {
"attributes": ["speed"],
"format": "keyValues",
"endpoint": {
"uri": "https://putsreq.com/2ZvwbG0bl1NvZF1KLTjo",
"accept": "application/json"
}
},
"@context": [
"http://example.org/cim/vehicle.jsonld"
]
}
{
"id": "5aeb0ee97",
"subject": {
"entities": [
{
"idPattern": ".*",
"type": "Vehicle"
}
],
"condition": {
"attrs": ["speed"],
"expression": {
"q": "speed>50",
"georel": "near;maxDistance:2000",
"geometry": "point",
"coords": "100,-1"
}
}
},
"notification": {
"attrs": ["speed"],
"attrsFormat": "keyValues",
"http": {
"url": "https://putsreq.com/2ZvwbG0bl1NvZF1KLTjo"
}
}
}

31
Context Subscription - HTTP Binding
§ Create Subscription
§ POST {apiEndPoint}/subscriptions/ à 201 Created
§ Update Subscription
§ PATCH {apiEndPoint}/subscriptions/{subscriptionId} à 204 No Content. 404 if not found
§ Remove Subscription
§ DELETE {apiEndPoint}/subscriptions/{subscriptionId} à 204 No Content. 404 if not found.
§ List Subscriptions
§ GET {apiEndPoint}/subscriptions/
§ Returns JSON Array
§ Retrieve Subscription by id
§ GET {apiEndPoint}/subscriptions/{subscriptionId}
§ Returns JSON Object

Context Source Registration
32

33
Context Source Registration - Description
§ You can register Context Sources capable of providing Context Information concerning
§ A particular Entity id / Set of Entities / Any Entity
§ An Entity Type / Set of Entity Types
§ A particular set of Entity Attributes i.e. Properties or Relationships / Any Attribute (of an Entity
or any Entity)
§ Additionally it can be provided
§ A geographical area associated to the Context Source i.e. an area for which the Context
Source has Context Information
§ Ex: a Context Source capable of providing Context Information for a whole Smart City
§ (A time scope. To be refined in the final NGSI-LD specification)
§ The Orion Broker implementation can even forward requests to Context Sources when
querying entities

34
Context Source Registration - Representation
{
"id": "urn:ngsi-ld:ContextSourceRegistration:csr1a3456",
"type": "ContextSourceRegistration",
"information": [
{
"entities": [
{
"type": "Vehicle"
}
],
"properties": ["brandName","speed"],
"relationships": ["isParked"]
}
],
"endpoint": "http://my.csource.org:1026",
"location": {
"type": "Polygon",
"coordinates": [
[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0],
[100.0, 1.0], [100.0, 0.0] ] ]
},
"@context": [
"http://example.org/cim/commonTerms.jsonld",
"http://example.org/cim/vehicle.jsonld",
]
}
{
"id”: "csr1a3456"
"dataProvided": {
"entities": [
{
"type": "Vehicle"
}
],
"attrs": [
"brandName", "speed", "isParked"
]
},
"expression": {
"geometry": "polygon",
"georel": "within",
"coords": "0.0,100.0;0.0,100;1.0,101.0;1.0,100.0;0.0,100.0"
},
"provider": {
"http": {
"url": "http://contextsource.example.org"
},
"legacyForwarding": true
}
}

35
Context Source Registration - HTTP Binding
§ Create Context Source Registration
§ POST {apiEndPoint}/registrations/ à 201 Created
§ Update Context Source Registration
§ PATCH {apiEndPoint}/registrations/{registrationId} à 204 No Content. 404 if not found.
§ Remove Context Source Registration
§ DELETE {apiEndPoint}/registrations/{registrationId} à 204 No Content. 404 if not found.
§ Query Context Source Registrations
§ GET {apiEndPoint}/registrations/?<Same as Query Entities>
§ Returns JSON Array of ContextSourceRegistrations
§ Retrieve Context Source Registration
§ GET {apiEndPoint}/registrations/{registrationId}
§ Returns JSON Object

37
FIWARE Context Broker (Orion)
MongoDB

38
Remarks – Orion
§ MongoDB as persistent data store
§ Implements the “NGSIv2 flavour”. In the future NGSI-LD
§ Multitenant (Fiware-Service HTTP header) àMultiple Mongo Databases.
§ Battle-tested. Deployed in various smart city projects.
§ Can play the role of Central Broker or Distribution Broker. Federated.
§ Source code
§ https://github.com/fiware/context.Orion
§ How to run
$ wget https://raw.githubusercontent.com/Fiware/context.Orion/master/docker/docker-
compose.yml
$ docker-compose up
$ curl localhost:1026/version

39
Other implementations
§ Aeron Broker (a.k.a. IoT Broker)
§ https://github.com/Aeronbroker/Aeron
§ Distribution broker
§ Experimental
§ OMA NGSI10/9 compliant
§ IoT Discovery
§ https://github.com/Aeronbroker/NEConfMan
§ Registry for distribution brokers
§ Experimental
§ OMA NGSI9 compliant

41
NGSI-LD implementation Roadmap
§ Short term. Quick win. Planned June 2018.
§ A plugin (proxy-wrapper) on top of the Orion Context Broker
§ NGSI-LD Wrapper implemented in Scala / Scalatra. Drop existing Java /Jersey one.
§ Automatic mapping between the NGSIv2 representation and the NGSI-LD representation
§ docker-compose to make the two services working together seamlessly
§ Medium term. Planned December 2018.
§ Native implementation, i.e. a new release of the Orion Context Broker.
§ Converge the NGSIv2 representation with the NGSI-LD representation
§ Target: Design for backwards and forwards compatibility
§ Longer term. Planned Q1 2019
§ Full @context, namespace support. Advanced Queries.
§ Historical data support (through the QuantumLeap plugin)

42
Related content
§ Open API specification (NGSIv2. NGSI-LD coming soon)
§ https://bit.ly/2I9ZWfe
§ Orion in HA Mode
§ https://fiware-orion.readthedocs.io/en/master/admin/extra/ha/index.html
§ Tutorials (NGSIv2 flavour. NGSI-LD coming soon)
§ https://github.com/Fiware?utf8=%E2%9C%93&q=tutorials&type=&language=
§ Generating historical data
§ http://fiwaretourguide.readthedocs.io/en/latest/generating-historical-context-information-sth-comet/how-to-
generate-the-history-of-Context-Information-using-STH-Comet/ (old API. MongoDB based)
§ http://fiwaretourguide.readthedocs.io/en/latest/storing-data-cygnus-mysql/how-to-store-data-cygnus-mysql/
§ https://github.com/smartsdk/ngsi-timeseries-api (NGSIv2 aligned, CrateDB, Grafana Ready!)
§ Harmonized Data Models (NGSIv2 flavour. Soon NGSI-LD)
§ https://schema.fiware.org

Thank you!
http://fiware.org
Follow @FIWARE on Twitter
José Manuel Cantera Fonseca
FIWARE Foundation Senior Expert
Josemanuel.cantera@fiware.org

FIWARE Global Summit - FIWARE Context Information Management

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (20)

Semelhante a FIWARE Global Summit - FIWARE Context Information Management

Semelhante a FIWARE Global Summit - FIWARE Context Information Management (20)

Mais de FIWARE

Mais de FIWARE (20)

Último

Último (20)

FIWARE Global Summit - FIWARE Context Information Management