This training camp teaches you how FIWARE technologies and iSHARE, brought together under the umbrella of the i4Trust initiative, can be combined to provide the means for creation of data spaces in which multiple organizations can exchange digital twin data in a trusted and efficient manner, collaborating in the development of innovative services based on data sharing and creating value out of the data they share. SMEs and Digital Innovation Hubs (DIHs) will be equipped with the necessary know-how to use the i4Trust framework for creating data spaces!

1. NGSI-LD Concise Payloads and Merge-
Patch Operations
Advanced and Experimental Features in Orion LD
Jason Fox, Technical Evangelist, FIWARE Foundation

2. 1
Concise Format supported by Orion-LD
Potentially NGSI-LD 1.6.1
▪ Want to increase uptake of NGSI-LD by lowering barriers to entry for new
developers
▪ Remove the misconception that NGSI-LD is just "JSON-LD with type
attributes"
▪ Remove redundancy in payloads, to make it easier to for users to update
and consume context data. But any new payloads must still be:
▪ JSON-LD documents.
▪ Compatible with existing formats.
▪ Suitable for CRUD
▪ Lossless
▪ Try to get some mechanism for a simple value update like the NGSI-v2's
update value endpoint legitimately supported

3. Normalized Property
Concise Property
Concise Property Format
Input and Output format. Potentially NGSI-LD 1.6.1
Super Concise Property
▪ type is optional
▪ value is optional (if no sub-attributes present)
The concise format is shorter than normalized
but unlike key-values it is still lossless.
2
{
"temperature": {
"type" : "Property",
"value" : 100,
}
}
{
"temperature": {
"value" : 100,
}
}
{
"temperature": 100
}

4. Normalized GeoProperty
Concise GeoProperty
Concise GeoProperty format
Input and Output format. Potentially NGSI-LD 1.6.1
Super Concise GeoProperty
▪ type is optional
▪ value is optional (if no sub-attributes
present)
▪ GeoProperty is inferred if the type is a
supported GeoJSON type.
3
{
"location": {
"type" : "GeoProperty",
"value" : {
"type": "Point",
"coordinates": [-73.97, 40.77]
}
}
}
{
"location": {
"value" : {
"type": "Point",
"coordinates": [-73.97, 40.77]
}
}
}
{
"location": {
"type": "Point",
"coordinates": [-73.97, 40.77]
}
}

5. Normalized Relationship Concise Relationship
Concise Relationship format
Input and Output format. Potentially NGSI-LD 1.6.1
▪ type is optional
▪ object is mandatory
.
4
{
"providedBy": {
"type" : "Relationship",
"object" : "urn:ngsi-ld:Entity:001"
}
}
{
"providedBy": {
"object" : "urn:ngsi-ld:Entity:001"
}
}

6. Concise LanguageProperty (as Map)
Concise LanguageProperty (as Property)
Normalized LanguageProperty
Concise LanguageProperty format
Input and Output format. Potentially NGSI-LD 1.6.1
▪ type is optional
▪ languageMap is mandatory
.
5
{
"name": {
"type": "LanguageProperty",
"languageMap": {
"el": "Κωνσταντινούπολις",
"en": "Constantinople",
"tr": "İstanbul"
}
}
}
{
"name": {
"languageMap": {
"el": "Κωνσταντινούπολις",
"en": "Constantinople",
"tr": "İstanbul"
}
}
}
{
"name": {
"value": "Constantinople",
"lang": "en"
}
}

7. Orion-LD supports Concise Format for all /entities endpoints
Potentially all brokers by NGSI-LD 1.6.1
▪ GET {{orion-ld}}/ngsi-ld/v1/entities/?options=concise
▪ POST .{{orion-ld}}/ngsi-ld/v1/entities/
▪ GET {{orion-ld}/ngsi-ld/v1/entities/<entity-id>?options=concise
▪ POST PATCH {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>/attrs
▪ PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>/attrs/<attr-id>
▪ Plus all relevant Batch Operation endpoints:
POST .{{orion-ld}}/ngsi-ld/v1/entityOperations/xxx
6

8. New Context-Broker Operations in Orion-LD .
7

9. Eight HTTP Methods - What do they mean?
▪ GET Retrieve data from server
▪ POST Send data to server to create or update a resource
▪ DELETE Delete an existing resource
▪ PATCH Apply partial modifications to a resource
▪ PUT Overwrite/Replace an existing resource
▪ OPTIONS Preflight Request - What operations are available?
HEAD Retrieve data from server (Headers Only)
▪ TRACE Message loop-back for debugging
8

10. Two new PUT Operations
▪ Replace a Complete Entity
PUT {{orion}}/ngsi-ld/v1/entities/<entity-id>
▪ Overwrite an Entire Attribute
PUT {{orion}}/ngsi-ld/v1/entities/<entity-id>/attrs/<attr-id>
▪ Supports normalized and concise payloads
▪ Pedantically Orion-LD "misuses" this HTTP verb as the operation is not
completely idempotent - the modifiedAt system attribute is still updated whenever
a PUT occurs
▪ Batch Operation Equivalent:
POST {{any-broker}}/ngsi-ld/v1/entityOperations/update?options=overwrite
9

11. One new PATCH Endpoint
▪ Merge an Entity
PATCH {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>
▪ Merge Patch rather than existing Partial Update Patch
▪ Supports normalized, concise and key-values payloads
PATCH {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>?options=keyValues
▪ Supports the update of a common observedAt Property-of-a-Property
PATCH {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>?observedAt=XXX-XXX
▪ Supports payloads including Language Maps as a Property
PATCH {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>?lang=fr
10

12. PATCH Endpoints
● Partial Update Operations
● Merge Operations
11

13. Original Entity
Result: Updated Entity
Partial Update of an Entity
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>/attrs
Normalized Payload:
▪ value updated to 100
▪ observedAt updated
▪ unitCode removed
▪ Other Attributes unchanged
temperature attribute replaced with payload
contents
12
{
"id": "urn:ngsi-ld:Sensor:001",
"type": "TemperatureSensor",
"temperature": {
"type" : "Property",
"value" : 25,
"unitCode": "CEL"
"observedAt": "2022-01-01"
}
}
{
"id": "urn:ngsi-ld:Sensor:001",
"type": "TemperatureSensor",
"temperature": {
"type" : "Property",
"value" : 100,
"observedAt": "2022-03-14"
}
}
{
"temperature": {
"type" : "Property",
"value" : 100,
"observedAt": "2022-03-14"
}
}

14. Original Entity
Result: Updated Entity
Partial Update of an Attribute
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>/attrs/temperature
Normalized Payload:
▪ value updated to 100
▪ observedAt updated
▪ unitCode not removed
▪ Other Attributes unchanged
temperature sub-attribute replaced with
payload contents
13
{
"id": "urn:ngsi-ld:Sensor:001",
"type": "TemperatureSensor",
"temperature": {
"type" : "Property",
"value" : 25,
"unitCode": "CEL”,
"observedAt": "2022-01-01"
}
}
{
"id": "urn:ngsi-ld:Sensor:001",
"type": "TemperatureSensor",
"temperature": {
"type" : "Property",
"value" : 100,
"unitCode": "CEL"
"observedAt": "2022-03-14"
}
}
{
"type" : "Property",
"value" : 100,
"observedAt": "2022-03-14"
}

15. Original Entity
Result: Merged Entity
🆕 Merge of an Entity (1) - Normalized Payload Support
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>
Normalized Payload:
▪ value updated to 100
▪ observedAt not removed
▪ unitCode not removed
▪ Other Attributes unchanged
Values from the payload contents merged with
existing entity. Unchanged data does not need to
be supplied
14
{
"id": "urn:ngsi-ld:Sensor:001",
"type": "TemperatureSensor",
"temperature": {
"type" : "Property",
"value" : 25,
"unitCode": "CEL”,
"observedAt": "2022-01-01"
}
}
{
"id": "urn:ngsi-ld:Sensor:001",
"type": "TemperatureSensor",
"temperature": {
"type" : "Property",
"value" : 100,
"unitCode": "CEL”,
"observedAt": "2022-01-01”
}
}
{
"temperature": {
"type" : "Property",
"value" : 100,
}
}

16. Normalized Payload
Concise Property Payload
Merge of an Entity (2) - Concise Payload Support
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>
Super Concise Property
▪ value updated to 100
▪ observedAt not removed
▪ Other sub-attributes (e.g. unitCode)
not removed
▪ Other Attributes unchanged
Values from the payload contents merged with
existing entity.
15
{
"temperature": {
"type" : "Property",
"value" : 100,
}
}
{
"temperature": {
"value" : 100,
}
}
{
"temperature" 100
}
Merge means unchanged data no longer needs to be supplied

17. Key-Values Payload (Lossy)
Merge of an Entity (3) - Key-Values Payload Support
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>?options=keyValues
Result
▪ name - Property type is maintained. value updated
▪ spouse - Relationship type is maintained. object updated
▪ Other attributes (e.g. born) remain unchanged
▪ All sub-attributes remain unchanged
Values from the payload contents intelligently merged with existing entity.
16
{
"name": "John Ono Lennon",
"spouse": "http://dbpedia.org/resource/Yoko_Ono"
}
Indicates a lossy payload where only values have been supplied

18. Normalized as Map (Lossless)
Normalized as Property (Lossy?)
Merge of an Entity (4) - Key-Values and LanguageMap Support
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>?options=keyValues&lang=en
Key-Values as Property (Lossy)
Result:
▪ en key of the languageMap updated to "Istanbul"
LanguageMaps have a dual identity as both a
JSON Object and a simple String. Supply a default
lang to indicate a default language to use in a
merge operation if necessary.
17
{
"name": {
"type": "LanguageProperty",
"languageMap": {
"el": "Κωνσταντινούπολις",
"en": "Constantinople",
"tr": "İstanbul"
}
}
}
{
"name": "Istanbul"
}
{
"name": {
"type": "Property",
"value": "Constantinople",
"lang": "en"
}
}

19. Normalized Payload
Concise Property Payload
Merge of an Entity (5) - Timestamp support
PATCH . {{orion-ld}}/ngsi-ld/v1/entities/<entity-id>?observedAt=XX-XX-XX
Super Concise Property
▪ value updated to 100
▪ observedAt updated (only where present)
▪ Other sub-attributes (e.g. unitCode)
not removed
▪ Other Attributes unchanged
Values from the payload contents merged with
existing entity.
18
{
"temperature": {
"type" : "Property",
"value" : 100,
}
}
{
"temperature": {
"value" : 100,
}
}
{
"temperature": 100
}
common updated ßobservedAt available for attributes

20. JSON literal null and PATCH Endpoints.
{"@type":"@json" "@value": null}
19

21. JSON-LD does not support direct use of null
Invalid JSON-LD
20
JSON-LD 1.1 Specification - § 4.2.2. JSON Literals
Generally, when a JSON-LD processor encounters null, the associated entry or value
is removed. However, null is a valid JSON token; when used as the value of a JSON
literal, a null value will be preserved.
{
"temperature": {
"type" : "Property",
"value" : 100,
"precision": null
}
}

22. NGSI-LD states PATCH uses null to indicate deletion
▪ Always encode null as a JSON literal
▪ null is useable to delete attributes on PATCH endpoints only:
• Partial Update
• Merge
Valid NGSI-LD
▪ Attempting to set any type, value or object directly to an encoded JSON
literal null results in a 400 Bad Request
21
{
"temperature": {
"type" : "Property",
"value" : 100,
"precision": {"@type":"@json" "@value": null}
}
}

23. Thank you!
http://fiware.org
Follow @FIWARE on Twitter