Home

Orion-LD Implementation Notes

Reference documents

• Gap Analysis. Summary of the main differences between NGSIv2 and NGSI-LD
• NGSI-LD. Preliminary Specification

Design Review Meeting Notes

mongoDB Data Model

• In the mongoDB documents associated to Entities it is preferred not to overload the metadata dictionary, to ensure future compatibility with Entities serialized using NGSIv2.

• Performance-wise it could be a good idea to store the alias of attributes as that would be needed at Entity rendering time.

URI design issues. Entity identifiers.

• Is there ambiguity in the following API URI?

GET /ngsi-ld/v1/entities/http://E1/attrs/A1

The response is: That URI is not a valid URI!!!

There should never be ambiguity because, as per RFC 3986, an Entity Id (represented by a URI) should be properly encoded when incorporated to an API URL. Thus,

there could be either two cases:

/ngsi-ld/v1/entities/http%3A%2F%2FE1%2Fattrs%2FA1

or

/ngsi-ld/v1/entities/http%3A%2F%2FE1/attrs/A1

which are unambiguous and the parser should take care of them.

Default @context vs Core @context

• The Core @context defines the API terms i.e. the vocabulary used by the API itself. The terms defined by the Core @context cannot be redefined by any user @context, i.e. any redefinition attempt shall be ignored.

• The Default @context includes the Core @context and just maps any term to a URI of the form

http://example.org/ngsi-ld/{term}

A Default @context definition can be found at https://github.com/Fiware/NGSI-LD_Tests/blob/master/ldContext/defaultContext.jsonld

It just takes advantage of the JSON-LD @vocab directive which allows to map terms to URIs by prefixing.

@context resolution

• It is not needed to serialise Core @context terms as the Core @context is always implicitly present.

• When expanding terms of the user vocabulary (Entity Types, Attributes, etc. ) the user @context shall be used and not the core @context. The Core @context is defining the terms used by the API itself (the system) and as a result, in general, it should not be part of the user vocabulary.

• The only exception is the "location" attribute which is defined by the @core Context.

So if the alias "name" is used by the user it should not be mapped to "http://uri.etsi.org/ngsi-ld/name", but to whatever the user has defined in the @context, for instance.

"name": "http://schema.org/name" 

and if nothing is found in the user @context, then it should be mapped to a default URI

http://example.org/ngsi-ld/name

MIME Types and Link Header

• application/ld+json indicates that the payload content is JSON-LD and the JSON-LD Link header, if present, shall be ignored. The @context shall be taken from the JSON object @context member. If no @context member is present then the Default @context shall be used.

• application/json indicates that the payload content is JSON and the JSON-LD header shall be used to obtain the @context. If a @context is present as member of an Entity then it shall result in a BadRequestData error.

misc issues

• s/cSourceRegistrations/csourceRegistrations/g

• URNs shall be validated against the grammar defined at IETF RFC 8141: "Uniform Resource Names (URNs)".