Skip to content

Home

Jump to bottom Edit New page
Jose M. Cantera edited this page Oct 2, 2018 · 36 revisions

Orion-LD Implementation Notes

Reference documents

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 URL is not well-formed as it includes the ':' and '/' as part of a URI component and they are reserved characters.

Literally from RFC 3986, "If data for a URI component would conflict with a reserved character's purpose as a delimiter, then the conflicting data must be percent-encoded before the URI is formed. "

There should never be ambiguity because every Entity Id (represented by a URI) shall be properly encoded when incorporated as a URI component of 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. The parser will properly 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, by default, terms to URIs by prefixing them.

@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 (system-defined terms).

  • The only exception is the "location" Attribute which is defined by the @core Context and used as a regular Entity Attribute.

Example:

If the alias "name" is used for an attribute 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 (as per the Default @context).

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

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.

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.

Misc issues found

  • s/cSourceRegistrations/csourceRegistrations/g

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

Fermín's raw notes on September 27th 2018 audio

  • Current functionality in the reviewed PR covers basically entity creation plus retrieval of context documents (including several levels of indirection?)
  • A review of the functional tests (news and old) is done. There wasn't time to review the code parts :(
  • A cache of context is hold in memory (not sure of having understanding this correctly... I could be wrong)
  • Types and attributes in NGSI are identified by URI+alias. URI can be a URL or a URN.
  • Entity IDs are URI
  • URI syntax is check by the own code (i.e. no extra lib for that)
  • Concerns about how the current data model ("entities" collection in MongoDB) is used. The most important concerns are: 1) alias should be used in the key-map to align with NGSIv2, 2) context URL should be added as an extra field, 3) metadata should not be overloaded to store alias (would break NGSIv2 compatibility). It is important to define a good data model, otherwise interoperability scenarios will not be possible.
  • One of the function tests (0000_ngsild/ngsild_url_parse.test) is a good summary of all the URL requests patterns that JSON-LD support. Note that some pieces of the URL can be URL in sequence.
  • Fermín thinks that the URL routing currently implemented in Orion could cope with the above case with small changes. He will try to confirm/discard it with a real test in the code.
  • 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.
Add a custom footer
Add a custom sidebar
Clone this wiki locally