FIWARE Training: NGSI-LD Concise Payloads and Merge-Patch Operations
0 likes31 views
The document outlines the advanced features of ngsi-ld, particularly focusing on the concise payloads and merge-patch operations facilitated by the Orion-LD context broker. Key updates include nuanced payload structures for properties, geoproperties, relationships, and language properties, aimed at improving compatibility and efficiency in data handling. Additionally, it describes new HTTP operations related to entity management, emphasizing the ability to support both normalized and concise formats.
![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]
}
}](https://image.slidesharecdn.com/fiwaretraining-ngsi-ld-concise-merge-patch-220713095916-776d9738/85/FIWARE-Training-NGSI-LD-Concise-Payloads-and-Merge-Patch-Operations-4-320.jpg)
FIWARE Training: NGSI-LD Concise Payloads and Merge-Patch Operations
- 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