Skip to content

Orion LD Implementation Notes

Jump to bottom Edit New page
Jose M. Cantera edited this page Jan 15, 2019 · 6 revisions

Implementation Notes / Clarifications

Dear developer,

These implementation notes are here to help you. However, we encourage you to read the NGSI-LD specification.

Reference documents

Design Review Meeting Notes

Fermin 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 ':' and '/', which are reserved characters, as part of a URI component.

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. "

Thus, 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 (entities/{entityId}). 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.

If a developer does not encode properly an Entity Id then she will never be able to retrieve her entities.

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.

Term to URI expansion through the @context.

  • 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

  • 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.

Orion @context servicing requests

  • Implement GET /ngsi-ld/ex/v1/contexts/$(uriEncode(entity-id>))
  • Look up entity-id and give back @context from the entity.
  • If @context value is string or vector, add Core Context and vocab context (Default URL) before returning
  • If @context value is object, return the "simple" key-value list
    • What about contexts not invented/serviced by orionld, like the core context (orionld has them in its context-cache and could easily serve them) GET /ngsi-ld/ex/v1/contexts/$(uriEncode(URL-TO-EXTERNAL-CONTEXT)) ?

o task/26.orionld-user-context-includes-builtin-context If a user context contains the Core Context or the Vocab-Default-URL Context, silently disable it from User context and treat as Core/vocab contexts, as always. [ A new field: 'bool enabled' needed in the struct OrionldContext ] When the context is served (GET /ngsi-ld/ex/v1/contexts/XXX), the new field 'bool enabled' is ignored and all of the original context is returned.

  • But, in "task/25.orionld-context-servicing" we have already stated that the Core/Vocab contexts have to be added before returning ... Might be better to simply remove the Core/Vocab contexts from the User context ...

@context Resolution.

  • If the request verb is POST or PATCH and the Content-Type header is "application/ld+json", then the associated @context shall be obtained from the input payload itself. If no @context can be obtained from the input payload, then an HTTP error response of type BadRequestData shall be raised.

  • If the request verb is POST or PATCH and the Content-Type header is "application/json", then the @context shall be obtained from a Link header as mandated by JSON-LD [2], clause 6.8. In the absence of such Link header, then the "@context" 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?._ An error shall be raised indicating that MIME type shall be 'application/ld+json'_.

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)".

Add a custom footer
Add a custom sidebar
Clone this wiki locally