Skip to content

Commit 4634157

Browse files
jason-foxjason-fox
committed
Updating texts
1 parent 000f60b commit 4634157

1 file changed

Lines changed: 121 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 121 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,124 @@ The tutorial uses [cUrl](https://ec.haxx.se/) commands throughout, but is also a
2828
>
2929
> — Sophocles, Oedipus at Colonus
3030
31+
The NGSI-LD API is a flexible mechanism for producing context data in mulitple formats.
32+
This was demonstrated in the initial Getting Started [tutorial](https://github.com/FIWARE/tutorials.Getting-Started/tree/NGSI-LD) where both "normalized" and "key-values" pairs format were produced. The default, verbose data format is so-called "normalized" NGSI-LD where every **Property** is defined by `"type": "Property`
33+
and every **Relationship** is defined by `"type": "Relationship`. These keywords ( `type`, `Property` and `Relationship`) are in turn strictly defined JSON-LD terms which can be found in the core @context served with every request.
34+
35+
36+
### Normalized NGSI-LD
37+
38+
The full "normalized" form is an excellent choice for data exchange, since through the the `@context` and the definition of JSON-LD keywords, machines are given all the tools to fully comprehend
39+
the payload format. Responses return the complete current state of each entity, with payloads all including sub-attributes such as Properties-of-Properties,
40+
Properties-of-Relationships and other standard metadata terms like `observedAt` and `unitCode`. Furthermore normalized payloads are exceedingly regular and parseable, and can easily be reduced down to the relevant `value` elements if such an operation necessary. However with the normalized format, is necessary to repeatedly supply common defining attributes such as `"type": "Property` throughout the payload to ensure that machines can fully understand the data represented.
41+
42+
#### Normalized NGSI-LD using `options=normalized`
43+
44+
```json
45+
{
46+
"@context": [
47+
"https://fiware.github.io/tutorials.Step-by-Step/example.jsonld",
48+
"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.4.jsonld"
49+
],
50+
"id": "urn:nsgi-ld:Beatle:John_Lennon",
51+
"type": "Beatle",
52+
"age": {"type": "Property", "value": 40, "unitCode" : "ANN"},
53+
"name": {"type": "Property", "value": "John Lennon"},
54+
"born": {"type": "Property", "value": "1940-10-09"},
55+
"spouse": {
56+
"type": "Relationship",
57+
"object": "urn:nsgi-ld:Person:Cynthia_Lennon"
58+
},
59+
"location": {
60+
"type": "GeoProperty",
61+
"value": {
62+
"type": "Point",
63+
"coordinates": [-73.975, 40.775556]
64+
}
65+
}
66+
}
67+
```
68+
69+
70+
Open in [**JSON-LD Playground**](https://tinyurl.com/4nw9z83m)
71+
72+
73+
74+
### Simplified NGSI-LD
75+
76+
The use of the normalized format can be contrast with the "key-values" pairs format, which is a simplified version concentrating purely on the values of the first level of attributes only. The payloads are remain regular, but are much shorter and to the point, and not all information is returned by the request - `unitCode` and `observedAt` will not be returned in the payload.
77+
78+
#### Simplified NGSI-LD using `options=keyValues`
79+
80+
```json
81+
{
82+
"@context": [
83+
"https://fiware.github.io/tutorials.Step-by-Step/example.jsonld",
84+
"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.4.jsonld"
85+
],
86+
"@id": "urn:nsgi-ld:Beatle:John_Lennon",
87+
"name": "John Lennon",
88+
"born": "1940-10-09",
89+
"spouse": "urn:nsgi-ld:Person:Cynthia_Lennon",
90+
"age": 40,
91+
"location": {
92+
"type": "Point",
93+
"coordinates": [-73.975, 40.775556]
94+
}
95+
}
96+
```
97+
98+
99+
Open in [**JSON-LD Playground**](https://tinyurl.com/2p93h8p6)
100+
101+
102+
This key-values payload matches the simple JSON-LD payload which can be seen on the front-page of the official [JSON-LD website](https://json-ld.org/)
103+
104+
Both normalized and key-values NGSI-LD formats are valid JSON-LD, but since the key-values format is lossy, until recently, all updates to an NGSI-LD context broker must be made using the normalized format.
105+
106+
### Concise NGSI-LD
107+
108+
To make the API easier to use and reduce the burden on developers, NGSI-LD now accepts an intermediate "concise" format which still offers all of the context data in the payload, but
109+
removes the redundancy of repeatedly adding `"type": "Property` throughout each payload. The concise representation is a terser, lossless form of the normalized representation, where redundant "type" members are omitted and the following rules are applied:
110+
111+
- Every **Property** without further sub-attributes is represented by the Property value only.
112+
- Every **Property** that includes further sub-attributes is represented by a value key-value pair.
113+
- Every **GeoProperty** without further sub-attributes is represented by the GeoProperty’s GeoJSON representation only
114+
- Every **GeoProperty** that includes further sub-attributes is represented by a value key-value pair.
115+
- Every **LanguageProperty** is defined by a languageMap key-value pair.
116+
- Every **Relationship** is defined by an object key-value pair.
117+
118+
119+
120+
#### Concise NGSI-LD using `options=concise`
121+
122+
```json
123+
{
124+
"@context": [
125+
"https://fiware.github.io/tutorials.Step-by-Step/example.jsonld",
126+
"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.4.jsonld"
127+
],
128+
"@id": "urn:nsgi-ld:Beatle:John_Lennon",
129+
"name": "John Lennon",
130+
"born": "1940-10-09",
131+
"spouse": {
132+
"object": "urn:nsgi-ld:Person:Cynthia_Lennon"
133+
},
134+
"age": {"value": 40, "unitCode" : "ANN"},
135+
"location": {
136+
"type": "Point",
137+
"coordinates": [-73.975, 40.775556]
138+
}
139+
}
140+
```
141+
142+
143+
144+
145+
In summary, all formats provide a regular, well-defined payload, but the "normalized" format
146+
is verbose and lossless, "key-values" is short and lossy, and third format - "concise" is an
147+
intermediate format created to bridge the gap between the two.
148+
31149

32150

33151

@@ -47,10 +165,9 @@ seen on the UltraLight device monitor web page found at: `http://localhost:3000/
47165
# Architecture
48166

49167
This application builds on the components and dummy IoT devices created in
50-
[previous tutorials](https://github.com/FIWARE/tutorials.IoT-Agent/). It will use three FIWARE components: the
51-
[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/), the
52-
[IoT Agent for Ultralight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/), and
53-
[QuantumLeap](https://smartsdk.github.io/ngsi-timeseries-api/) .
168+
[previous tutorials](https://github.com/FIWARE/tutorials.IoT-Agent/). It will use two FIWARE components: the
169+
[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) and the
170+
[IoT Agent for Ultralight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/).
54171

55172
Therefore the overall architecture will consist of the following elements:
56173

@@ -64,19 +181,13 @@ Therefore the overall architecture will consist of the following elements:
64181
and convert them to
65182
[UltraLight 2.0](https://fiware-iotagent-ul.readthedocs.io/en/latest/usermanual/index.html#user-programmers-manual)
66183
commands for the devices
67-
- FIWARE [QuantumLeap](https://smartsdk.github.io/ngsi-timeseries-api/) subscribed to context changes and
68-
persisting them into a **CrateDB** database
69184

70185
- A [MongoDB](https://www.mongodb.com/) database:
71186

72187
- Used by the **Orion Context Broker** to hold context data information such as data entities, subscriptions and
73188
registrations
74189
- Used by the **IoT Agent** to hold device information such as device URLs and Keys
75190

76-
- A [CrateDB](https://crate.io/) database:
77-
78-
- Used as a data sink to hold time-based historical context data
79-
- offers an HTTP endpoint to interpret time-based data queries
80191

81192
- An HTTP **Web-Server** which offers static `@context` files defining the context entities within the system.
82193
- The **Tutorial Application** does the following:

0 commit comments

Comments
 (0)