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. In other words, alias should be used in the key-map to align with NGSIv2.

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

• context URL should be added as an extra field

Overall, It is important to define a good data model, otherwise interoperability scenarios will not be possible.

Test issues

The are modifications in existing .test but seems to be minor things that, eventually, will be re-aligned with the existing .test if this is merged sometime into Orion main code. Similar changes to align in the functional .test framework (testHarness.sh / harnessFunctions.sh). Part of the unit tests (the ones which "bother") has been disabled.

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 each JSON-LD object @context member. If no @context member is present then an error shall be raised. See specification section 6.3.5.

• application/json indicates that the payload content is JSON and the JSON-LD header shall be used to obtain the @context. If no Link header is present then the @context used shall be the Default @context.

• Specification gap: What if MIME type is application/json and the Entity includes a @context member and no Link header is present?. Should the @context just be ignored? Should it be used? Treated as a regular Entity member? Raise an error?

MIME Type (Output payload). Section 6.3.6

• If the Accept header contains "application/json" but not "application/ld+json" then the response's ContentType shall be "application/json" and such response shall include a Link to the associated JSON-LD @context
• If the Accept header contains "application/ld+json", then the output payload provided by the HTTP response shall include the corresponding JSON-LD @context.

Term to URI Expansion Rules (GET, DELETE operations)

In GET or DELETE operations the term to URI expansion shall be performed using the JSON-LD @context referenced by the JSON-LD Link header.

Misc issues found

• s/cSourceRegistrations/csourceRegistrations/g

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