Implementors FAQ

This FAQ compilation is intended to clarify NGSI-LD specification by providing answers to common questions that implementors may have. Also it can help users of the API to solve their doubts.

• Q: What are the main (essential) differences between NGSI v2 and NGSI-LD?

  • R: The following:
    • The underlying Data Model is the Property Graph Data Model. Here you can see an example.
    • Entity Ids shall be URIs (URLs or URNs)
    • The metadata dictionary disappears. Metadata are represented by Properties of Properties.
    • There is some "metadata" standardised (unitCode, observedAt, ...)
    • There is a new type of Attribute Relationship intended to link one Entity to another Entity. That is done through the object member.
    • Geospatial properties are represented using the Attribute type GeoProperty.
    • The type of Attributes can only be Property, Relationship or GeoProperty.
    • A JSON-LD @context (a hash mapping names to URIs) can be added to Entities to provide Fully Qualified Names (URIs) associated to terms.
    • Overall the REST API is quite similar (even more simple) than the NGSI v2, although subscription payloads change a bit (but they are the same in essence).

• Q: Could you give me some examples of NGSI-LD payloads?

  • R: See this test

• Could you give me some examples of of JSON-LD @context?

  • R: Yes, here you can find one.

• Q: What is a Property of a Property / Relationship?

  • R: It is similar to NGSI v2 metadata. In this test 'P1_P1' is a Property of 'P1'. In NGSI v2 it would have been represented as a member of the metadata dictionary.

• Q: Property and Relationship can be arbitrarily nested?

  • R: Yes, but only one or two nesting levels could make sense in a real world scenario.

• Q: What is observedAt?

  • R: It is a timestamp associated to a Property or Relationship. See this test. In NGSI v2 it was usually specified using the timestamp metadata member.

• Q: How geo-location is represented?

  • R: See this example In essence an Attribute of type GeoProperty plus GeoJSON.

• Q: How DateTime is represented?

  • R: See this example

  For more details, see also Supporting-DateTime

• Q: Is application/json supported as MIME type?

  • R: Yes, indeed. However, the @context has to be externally provided, or no @context at all. In the latter case Entities will be under the Default @context. You can see an example here

• Q: What happens if I only use the

• Q: What is the JSON-LD Link header?

  • R: It is a standard HTTP Link Header intended to provide a @context in two scenarios:
    1. when application/json is used as MIME type.
    2. in GET and DELETE operations to specify what is the @context to be used for mapping types or attribute names to Fully Qualified Names (URIs).

• Q: Could you put an example of a JSON-LD HTTP Link Header?

  • R: You can see it here

• Q: Is the @context mandatory?

  • R: For JSON-LD content, yes. (application/ld+json).

• Q: How terms are mapped to URIs?. Please explain the logic behind it.

  • R:

• Q: What happens if an Entity Id is a URL?

  • R: Nothing. Entity Ids have to be encoded. Se more details here [].

• Q: Where I can find the default @context?

  • R: https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld