smart-data-models/data-models

Details needed on x-ngsi

dpatil-fw opened this issue · 6 comments

dpatil-fw commented

This yaml file: https://fiware.github.io/tutorials.NGSI-LD/models/schema.org.yaml has several x-ngsi attributes defined in detail for email attribute.
x-ngsi:
model: "https://schema.org/Text"
type: Property
uri: "https://schema.org/email"
uri-prefix: "https://schema.org/"

In https://github.com/smart-data-models/dataModel.PointOfInterest/blob/master/PointOfInterest/model.yaml only
x-ngsi: model is defined and only for a few fields

Similarly, for location, this https://github.com/smart-data-models/data-models/blob/master/ngsi-ld.yaml contains detailed x-ngsi:
x-ngsi:
model:
- "https://purl.org/geojson/vocab#Point"
- "https://purl.org/geojson/vocab#LineString"
- "https://purl.org/geojson/vocab#Polygon"
- "https://purl.org/geojson/vocab#MultiPoint"
- "https://purl.org/geojson/vocab#MultiLineString"
- "https://purl.org/geojson/vocab#MultiPolygon"
type: GeoProperty
uri: "https://uri.etsi.org/ngsi-ld/location"
uri-prefix: "https://uri.etsi.org/ngsi-ld/"

However location in https://github.com/smart-data-models/dataModel.PointOfInterest/blob/master/PointOfInterest/model.yaml, doesn't contain reference to x-ngsi

Have a few questions:

  1. This javascript: https://github.com/FIWARE/tutorials.Understanding-At-Context/blob/master/context-file-generator/bin/jsonld.js
    generates context.jsonld from yaml files
    If x-ngsi (uri, uri-prefix) is not mentioned in model.yaml, the prefix 'fiware' is generated instead of 'schema' in the generated context.jsonld file.
    For instance "email": "fiware:email" is generated instead of "email": "schema:email". The prefix schema seems more apt for some of the base attributes as they are derived from there. Where can I find more info on "x-ngsi" in fiware docs?

  2. I don't see x-ngsi mentioned in any schema.json files. However I do see it in some model.yaml files. If model.yaml is auto-generated from schema.json, how does it fetch this property? There seems to be no consistency in x-ngsi representation in many yaml files. Will be nice to have one sample reference file for this.

albertoabellagarcia commented

Regarding what is in FIWARE models repository it can be inconsistent because itt is frozen and no longer evolved.
Other questions need to review.

albertoabellagarcia commented

regarding question 1 I am gathering data from the authors who are my colleagues in the foundation.
regarding question 2. you are right. model.yaml is generated automatically from schema.json this is quite explained in the contribution manual that this file is automatically generated.

jason-fox commented

The https://fiware.github.io/tutorials.NGSI-LD/models/schema.org.yaml file is just defining data models using OpenAPI 3.0 a.k.a Swagger format. x-ngsi, as the name suggests is just a Specification Extension attribute - usually it is not relevant, and indeed you could generate a simple @context file without it, but the data held within in has been used to help generate a rich @graph and more comprehensive documentation.

It is true that the simple NGSI-LD @context generator in the tutorial defaults to uri.fiware.org namespaces and updates with corrected URIs based on the x-ngsi.uri and x-ngsi.uri-prefix attributes. The code and defaults can be altered if necessary.

dpatil-fw commented

Thanks for all the clarifications. I was able to proceed with my requirement by specifying x-ngsi.uri and x-ngsi.uri-prefix.
While there is no need to alter the code and defaults, mentioning a few lines about x-ngsi or giving a reference to it from Fiware docs might give a better understanding and help someone in the future. Just my two cents.

jason-fox commented

Tutorial Documentation updated: FIWARE/tutorials.Understanding-At-Context@ee34388

@albertoabellagarcia - since both Smart Data Models and NGSI-LD Tutorials are using the x-ngsi extension to generate @context, you may want to add a similar note to the README - e.g.

## Full list of Data Models

A full list of the data models in json format can be found in the file
[official_list_data_models.json](https://github.com/smart-data-models/data-models/blob/master/specs/AllSubjects/official_list_data_models.json).
Further details on the available subjects, properties and their descriptions can be found at the [search tool](https://smartdatamodels.org/index.php/ddbb-of-properties-descriptions/)

+ > **Note:** The Data Models used here for `@context` generation are defined using OpenAPI 3.0
+ > [Swagger format](https://swagger.io/specification). To help with the generation of IRIs the specification has been
+ > extended with additional annotations as necessary. The `x-ngsi` attribute, as the name suggests is just a simple
+ > [Specification Extension](https://swagger.io/specification/#specificationExtensions) - usually it is not relevant to
+ > Swagger, and indeed you could generate a simple `@context` file without it, but the data held within in has been used
+ > to help generate a rich [`@graph`](https://w3c.github.io/json-ld-syntax/#dfn-graph-object) and more comprehensive
+ > documentation.
dpatil-fw commented

Thank you