Annex D (informative): Transformation Algorithms

D.1 Introduction

These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification [2]).

D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1)

This algorithm takes as input an NGSI-LD graph which top level node is a particular Entity and returns as output a JSON-LD document which represents all the data associated to the entity. The JSON-LD document (and its associated @context) corresponds to a representation of the Entity in JSON-LD as per the NGSI-LD Information Model.

NOTE:

An early implementation of this algorithm can be found at [i.5].

Let:

  • G be a graph defined as follows:
  • Let N be G’s top level node.
  • N is an Entity instance of type T or types Ts. Type name is “AliasT” or there is an Array of Type names [“AliasT1”, …,“AliasTn”], N’s identifier is I.
  • N has 0 or more associated Property. Each Property (Psi) is defined as follows:
  • Property type identifier is Pi.
  • Property name is “AliasPi”.
  • Property Value is Vi.
  • Property Value’s associated data type is Di.
  • N is the subject of 0 or more Relationship. Each Relationship is defined as follows:
  • Relationship type identifier is Ri.
  • Relationship name is “AliasRi”.
  • Relationship target object identifier is Robji.
  • O be a JSON object initialized to the empty object ({}).
  • C be a JSON-LD @context initialized as described by annex B.

The algorithm should run as follows, provided all the preconditions defined above are satisfied:

  1. Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> … <"AliasTn", Tn>.
  2. Add to O two new members:
  1. <"id", I>.
  1. <"type", "AliasT"> or <"type", ["AliasT1", ...,"AliasTn"]> .”>.
  1. For each Property Psi (Pi, “AliasP”, Vi, Di) associated to N:
  1. Run Algorithm ALG1.1 taking the following inputs:
  • Ps → Psi.
  • O → O.
  • C → C.
  1. For each Relationship Rs (Ri, AliasRi, Robji) associated to N:
  1. Run Algorithm ALG1.2 taking the following inputs:
  • Rs → Rsi.
  • O → O.
  • C → C.
  1. Return (O, C) and end of the algorithm.

D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1)

Let Ps be the Property that has to be transformed. It is defined by (P, “AliasP”, V, D), where P denotes a Property Type Id, “AliasP” is the Property name, V is the Property Value and D is the Property Value’s data type.

Ps might be associated to extra Properties or Relationships.

Let O be the output JSON-LD object and C the associated JSON-LD context:

  1. Execute the following steps:
  1. If no member with “AliasP” is present in O, add a new member to O with key “AliasP” and value an object structure, let it be named Op as defined in the following. Otherwise, add all existing members with “AliasP” to a JSON-LD array and in addition put the object structure Op as defined in the following:
  • <"type", "Property">.
  • If D is not a native JSON data type add a new member to Op with name “value” and which value has to be an object structure as follows:
  1. <"@type", D>.
  1. <"@value", V>.
  • Else If D is a native JSON data type add a new member to Op as follows:
  1. <"value", V>.
  1. Add a new member to C as follows:
  • <"AliasP", P>.
  1. For each Property associated to Ps (Pss) recursively run the present algorithm (ALG1.1) taking the following inputs:
  • Ps → Pss.
  • O → Op.
  • C → C.
  1. For each Relationship associated to Ps (Rss) run algorithm ALG1.2 taking the following inputs:
  • Rs → Rss.
  • O → Op.
  • C → C.
  1. Return (O,C) and end of the algorithm.

D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2)

Let Rs be the Relationship that has to be transformed. It is defined by (R, “AliasR”, Robj), where R denotes a Relationship Type Id, “AliasR” is the Relationship’s name and Robj is the identifier of the target object of the Relationship.

Rs might be associated to extra Properties or Relationships.

Let O be the output JSON-LD object and C the current JSON-LD context:

  1. Execute the following statements:
  1. If no member with “AliasR” is present in O, add a new member to O with key “AliasR” and value an object structure, let it be named Or, and defined as in the following. Otherwise, add all existing members with “AliasR” to a JSON-LD array and in addition put the object structure Or as defined in the following:
  • <"object", Robj>.
  • <"type", "Relationship">.
  1. For each Property associated to Rs (Pss) run the algorithm ALG1.1 taking the following inputs:
  • Ps → Pss.
  • O → Or.
  • C → C.
  1. For each Relationship associated to Rs (Rss) recursively run the present algorithm ALG1.2 taking the following inputs:
  • Rs → Rss.
  • O → Or.
  • C → C.
  1. Return (O,C) and end of the algorithm.