fiware / tutorials.understanding-at-context

:blue_book: FIWARE-LD 101: Understanding NGSI-LD `@context`

This tutorial introduces basics of common Linked Data concepts and Data Models for NGSI-LD developers. The aim is to design and create a simple interoperable Smart Agricultural Solution from scratch and explain how to apply these concepts to your own smart solutions.

Unlike the NGSI-v2 developer series, this series will take an NGSI-LD first approach and therefore starts with reiterating the fundamentals of Linked Data and its application to the NGSI-LD interface.

The tutorial is mainly concerned with online and command-line tooling.

Start-Up

NGSI-LD Smart Farm

NGSI-LD offers JSON-LD based interoperability used for Federations and Data Spaces. To run this tutorial with NGSI-LD, use the NGSI-LD branch.

git clone https://github.com/FIWARE/tutorials.Understanding-At-Context.git
cd tutorials.Understanding-At-Context
git checkout NGSI-LD

./services create
./services start

	📚 Documentation

License

MIT © 2020-2024 FIWARE Foundation e.V.

tutorials.understanding-at-context's Issues

@context-file representation of enums and relationships

Hi,

I have 2 questions regarding the @context-file in this tutorial:

1.
In the example the enum-values are included as own entries within the @context-file. It is stated:

If a computer encounters a category=barn then it should be possible to accertain that this category can be identified as a https://wiki.openstreetmap.org/wiki/Tag:building%3Dbarn.

I haven't found any details on expansion of property values in the NGSI-LD API spec v1.3.1. Did I miss smth. or is this just an assumption regarding the Context Broker implementation in this tutorial? Must the enum-values be included in the context?

2.
The @context-file includes several relationships, e.g. "providedBy": "fiware:providedBy". In the NGSI-LD API spec v1.3.1. section 4.5.1 regarding the content of the @context for an entity it is stated:

In addition to the terms defined by the Core NGSI-LD @context (mandatory as per annex B), the @context should contain the following terms:
[...]
One term associated to the name of each Relationship used by the entity representation, mapping the Relationship Name with the Relationship Identifier (URI) in the form:

• "@type": "@id".
• "@id": <Relationship's URI>.

With my understanding this implies that the format used in this tutorial does not follow this specification. Instead of "providedBy": "fiware:providedBy" it should be:

"providedBy": {
    "@type": "@id",
    "@id": ""fiware:providedBy" }
}

Context Generator | FIWARE context URL does not work

Possible issue

I think that the context URL associated with FIWARE - context.fiware = 'https://uri.fiware.org/ns/data-models#'; - in the file context-file-generator/bin/jsonld.js is outdated because it doesn't work.

Related question

Let me take this opportunity to ask this question: suppose I have a "Company" entity defined as follows in my OpenAPI specification:

Company:
      type: object
      allOf:
        - $ref: "https://smart-data-models.github.io/dataModel.Organization/Organization/model.yaml#/Organization"
        - $ref: "https://smart-data-models.github.io/data-models/schema.org.yaml#/ContactPoint"

In the context file generated with the above generator I end up with the following definition: "Company": "fiware:Company". In this case should I change the definition to "Company": "fiware:Organization" considering that the base model is called "Organization"?

Broken link to FIWARE data models

In the "Understanding At Context Tutorial" there is the following statement:

If a computer encounters an entity of type=Building this really refers to a https://uri.fiware.org/ns/data-models#Building

The link https://uri.fiware.org/ns/data-models#Building seems to be broken for me.
However, changing data-models to dataModels makes the link work.
Is it possible that the correct link should be https://uri.fiware.org/ns/dataModels#Building or am I missing something?

With kind regards
Max

Incorrect link to supermarket.yaml

This line:
The raw supermarket.yaml file is available here is linking to agriculture.yaml, please fix correct link to
https://github.com/FIWARE/tutorials.Understanding-At-Context/blob/master/supermarket.yaml

swagger validation error

./service validate baseline.yaml
is giving the following error:

Onoes! The API is invalid. Swagger schema validation failed.
Data does not match any schemas from 'oneOf' at #/components/schemas/PointOfInterest
Data does not match any schemas from 'oneOf' at #/components/schemas/PointOfInterest/properties/type
No enum match for: Property at #/properties/type/type
Missing required property: $ref at #/properties/type
Missing required property: $ref at #/components/schemas/PointOfInterest

The baseline.yaml is using the model.yaml defined in https://github.com/smart-data-models/dataModel.PointOfInterest/tree/master/PointOfInterest and I think the 'type' defined in the model.yaml is giving the error. Replacing "type": "Property" with "type": "string" sorts the error above. But what is the right way to define "type" in model.yaml?

This is the model.yaml referred:
https://raw.githubusercontent.com/smart-data-models/dataModel.PointOfInterest/master/PointOfInterest/model.yaml#/PointOfInterest

--- 
components: 
  schemas: 

    # This is the base definition of a PointOfInterest
    PointOfInterest: 
      $ref: "https://raw.githubusercontent.com/smart-data-models/dataModel.PointOfInterest/master/PointOfInterest/model.yaml#/PointOfInterest"


info: 
  description: "Base Model Definitions from Smart Data Models"
  title: Baseline Models
  version: "1.0.0"
openapi: "3.0.0"


# These paths are merely representative.
paths: 
  /ngsi-ld/v1/entities: 
    get: 
      responses: 
        ? "200"
        : 
          description:  OK
          content: 
            application/ld+json: 
              schema: 
                type: object

Cannot download data models when working under proxy

Hello,
I'm trying to execute this tutorial and got the following error:

./services validate ./baseline.yaml
Onoes! The API is invalid. Error downloading https://fiware.github.io/tutorials.NGSI-LD/models/openstreetmap.yaml 
getaddrinfo ENOTFOUND fiware.github.io

./services ngsi ./baseline.yaml
Creating a NGSI-LD @context file for normalized interactions
Cannot dereference file. The file is invalid. Error downloading https://fiware.github.io/tutorials.NGSI-LD/models/building.yaml 
getaddrinfo ENOTFOUND fiware.github.io
(node:1) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'components' of undefined
    at Object.getContext (/usr/src/app/bin/jsonld.js:73:19)
    at Object.ngsi (/usr/src/app/bin/swagger.js:49:37)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
(Use `node --trace-warnings ...` to show where the warning was created)
(node:1) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 3)
(node:1) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
datamodels.context-ngsi.jsonld created

I'm working under proxy of my company, so possibly, proxy causes this error.
I can access the links successfully on browser.
Is there any way to configure proxy to solve this problem?
Thank you for your support.

Incorrect generation of @Context-File if prefixes are used in variable names

Hello,

Summary

I followed this tutorial and used the context-file-generator to generate our custom @Context-File. Unfortunately the context-file-generator seems to generate wrong @Context-files that produce errors in production.

Steps to reproduce

I have generated the data model according to the instructions from https://github.com/FIWARE/tutorials.Understanding-At-Context:

1. First I generated a model.yaml file. I don't want to share our whole model file in github (please ping me if I should provide it for you for testing-purposes), but I give you an example for problematic entities:

  ###############################
  ## CompressedAirDistribution ##
  ###############################
  CompressedAirDistribution:
    description: "Process management system function 'Compressed air distribution' with KKS function code: 'QFB' (de: 'Druckluftverteilung')"
    required:
      - "id"
      - "type"
      - "dateObserved"
      - "isSubsystemOf"
    properties:
      id:
        anyOf:
          - description: "Property. Identifier format of any NGSI entity"
            maxLength: 256
            minLength: 1
            pattern: '^[\w\-\.\{\}\$\+\*\[\]`|~^@!,:\\]+$'
            type: "string"
          - description: "Property. Identifier format of any NGSI entity"
            format: "uri"
            type: "string"
        description: "Unique identifier of the entity"
        x-ngsi:
          type: "Property"
      type:
        description: "NGSI Entity type. It has to be 'CompressedAirDistribution' (a specific PCS part)"
        enum:
          - "CompressedAirDistribution"
        type: "string"
        x-ngsi:
          type: "Property"
      dateObserved:
        description: "Date of the observed entity defined by the user."
        type: "string"
        x-ngsi:
          type: "Property"
      isSubsystemOf:
        description: "This component is a sub component of another system"
        type: "string"
        x-ngsi:
          model: "https://schema.org/URL"
          type: "Relationship"
      kksFunction:
        description: "KKS function of property (level 1)"
        type: "string"
        x-ngsi:
          type: "Property"
      0QFB15CP001:Dr_DrLuAnl:U_AH:
        description: "Compressed air distribution Nr. 15 Measuring circuit Pressure Nr. 001  (HL alarm)"
        type: "boolean"
        x-ngsi:
          model: "https://schema.org/Boolean"
          type: "Property"
      0QFB15CP001:Dr_DrLuAnl:U_WL:
        description: "Compressed air distribution Nr. 15 Measuring circuit Pressure Nr. 001  (LL warning)"
        type: "boolean"
        x-ngsi:
          model: "https://schema.org/Boolean"
          type: "Property"
      0QFB15CP001:Dr_DrLuAnl:U_AL:
        description: "Compressed air distribution Nr. 15 Measuring circuit Pressure Nr. 001  (LL alarm)"
        type: "boolean"
        x-ngsi:
          model: "https://schema.org/Boolean"
          type: "Property"
      0QFB15CP001:Dr_DrLuAnl:U_WH:
        description: "Compressed air distribution Nr. 15 Measuring circuit Pressure Nr. 001  (HL warning)"
        type: "boolean"
        x-ngsi:
          model: "https://schema.org/Boolean"
          type: "Property"
      0QFB15CP001:Dr_DrLuAnl:U:
        description: "Compressed air distribution Nr. 15 Measuring circuit Pressure Nr. 001  (Analog value measurement)"
        type: "number"
        x-ngsi:
          model: "https://schema.org/Number"
          type: "Property"

3. then I checked its validity in Swagger-UI which has no issues

4. afterwards I used the Smart Data Model Tool to generate a @context file (see datamodels.context-ngsild.jsonld and datamodels.md)

Issue

Swagger and the tool say that the provided API is valid and successfully generate the @context-file. I can also work with the generated file using IoT-Agent for OPC UA, Orion-LD and halfway also Mintaka - Mintaka is successfully writing entities based on provided @context file, but it doesn't allow to use temporal interface based on that file. I discussed the issue in another issue with Mintaka developers: FIWARE/mintaka#167

According to @wistefan the reason why Mintaka declines the provided @context-file in read-requests is that the @context-file has been generated incorrectly. In case ":" are used, these prefixes also need to be declared in @context file. As an example

• This is the wrong @context produced by context-file-generator

  {
      "@context": {
          "type": "@type",
          "id": "@id",
          "ngsi-ld": "https://uri.etsi.org/ngsi-ld/",
          "fiware": "[https://uri.fiware.org/ns/data-models#](https://uri.fiware.org/ns/data-models)",
          "schema": "https://schema.org/",
          "0BLE10CS002:Drehzahl_DT:U": "fiware:0BLE10CS002:Drehzahl_DT:U"
      }
  }
  

• This would be the correct @context file with defined prefixes

  {
      "@context": {
          "type": "@type",
          "id": "@id",
          "ngsi-ld": "https://uri.etsi.org/ngsi-ld/",
          "fiware": "[https://uri.fiware.org/ns/data-models#](https://uri.fiware.org/ns/data-models)",
          "schema": "https://schema.org/",
          "0BLE10CS002" : "https://dlr.org/",
          "0BLE10CS002:Drehzahl_DT:U": {
            "@type":"fiware:0BLE10CS002:Drehzahl_DT:U"
        }
      }
  }
  

Expectations

From my understanding the variable names I defined are according to NGSI-LD standard:

So I would expect the context-file-generator to either throw an error if the variable names are not allowed (instead of claiming that API is valid) or generate the @context-file correctly.

It is also not expected that only Mintaka recognizes the wrong context-file in read-requests, but not in write-requests. Orion-LD and IoT-Agent for OPC UA don't seem to recognize wrong @context-file at all.

Generating @context-files

Hi,

is there a default way for generating @context-files based on customized Smart Data Models? The context-file-generator used in this tutorial seems to be based on @jason-fox swagger-datamodel-test tool.
Will this tool generate NGSI-LD v1.4.1 conform files?