Commit 92d61390 authored by Marco Cavalli's avatar Marco Cavalli
Browse files

chore: upload cim009v191 converted to md

parent 5d24072a
Loading
Loading
Loading
Loading
+1 −1
Original line number Diff line number Diff line
@@ -49,7 +49,7 @@ jspm_packages/
# Folders
node_modules
public
media*
md_to_docx_converter/**/media*
saved_files
official
editing
+34 −0
Original line number Diff line number Diff line
# Annex A (normative): NGSI-LD identifier considerations

## A.1 Introduction

The purpose of identifiers is to allow uniquely identifying NGSI-LD elements (Entities, Context Subscriptions or [Context Source Registrations]{.HTML_Keyboard}) within an NGSI-LD system. This annex is intended to clarify the different issues around the design of identifiers in NGSI-LD.

## A.2 Entity identifiers

In order to enable the participation of NGSI-LD in linked data scenarios, all Entities are identified by **URIs**. If those URIs are expected to participate in external linked data relationships they **should** be dereferenceable.

It is noteworthy that the identifier from the point of view of NGSI-LD is different from the inherent identifier that a specific Entity may have. For instance, an NGSI-LD Entity of Type ["Vehicle"]{.HTML_Code} may have a Property named *licencePlateNumber*, which it is actually a unique identifier from the point of view of the Entity domain, as it uniquely identifies the specific vehicle instance. However, from the point of view of the NGSI-LD system, it may have another identifier which might or might not include such licence plate number identifier.

## A.3 NGSI-LD namespace

NGSI-LD defines a specific URN [n.9] namespace intended to help API users to design readable, clean and simple identifiers. As it is based on URNs, the usage of this identification approach is not recommended when dereferenceable URIs are needed (fully-fledged linked data scenarios).

The referred namespace is defined as follows (to be registered with IANA):

- namespace identifier: NID = ["ngsi-ld"]{.HTML_Code}
- namespace specific string: NSS = EntityTypeName [":"]{.HTML_Code} EntityIdentificationString

*EntityTypeName* shall be an Entity Type name which can be expanded to a URI as per the *\@context*.

*EntityIdentificationString* shall be a string that allows uniquely identifying the subject Entity in combination with the other items being part of the NSS.

>>> [!tip] EXAMPLE:

[urn:ngsi-ld:Person:28976543]{.HTML_Code} .

>>>

It is recommended that applications use this URN namespace when applicable.

In general, the URN specification defines namespace equivalence in a case-insensitive manner, however it is assumed that context-broker implementations shall always use lowercase letters in namespaces where they have a choice in case, unless there is a strong reason otherwise. Restricting the namespace prefix to lower case [urn:ngsi-ld:]{.HTML_Code} can improve caching and retrieval, since this ensures since alphabetic characters within the namespace specific string are always consistent.
+453 −0
Original line number Diff line number Diff line
# Annex B (normative): Core NGSI-LD \@context definition

Below is the definition of the Core NGSI-LD *\@context* which shall be supported by implementations.

Such definition has been tested using [i.7].

``` json
{
  "@context": {
    "@version": 1.1,
    "@protected": true,
    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/",
    "geojson": "https://purl.org/geojson/vocab#",
    "id": "@id",
    "type": "@type",
    "Attribute": "ngsi-ld:Attribute",
    "AttributeList": "ngsi-ld:AttributeList",
    "ContextSourceIdentity": "ngsi-ld:ContextSourceIdentity",
    "ContextSourceNotification": "ngsi-ld:ContextSourceNotification",
    "ContextSourceRegistration": "ngsi-ld:ContextSourceRegistration",
    "Date": "ngsi-ld:Date",
    "DateTime": "ngsi-ld:DateTime",
    "EntityType": "ngsi-ld:EntityType",
    "EntityTypeInfo": "ngsi-ld:EntityTypeInfo",
    "EntityTypeList": "ngsi-ld:EntityTypeList",
    "ExecutionResultDetails": "ngsi-ld:ExecutionResultDetails",
    "Feature": "geojson:Feature",
    "FeatureCollection": "geojson:FeatureCollection",
    "GeoProperty": "ngsi-ld:GeoProperty",
    "GeometryCollection": "geojson:GeometryCollection",
    "JsonProperty": "ngsi-ld:JsonProperty",
    "LanguageProperty": "ngsi-ld:LanguageProperty",
    "LineString": "geojson:LineString",
    "ListProperty": "ngsi-ld:ListProperty",
    "ListRelationship": "ngsi-ld:ListRelationship",
    "MultiLineString": "geojson:MultiLineString",
    "MultiPoint": "geojson:MultiPoint",
    "MultiPolygon": "geojson:MultiPolygon",
    "Notification": "ngsi-ld:Notification",
    "Point": "geojson:Point",
    "Polygon": "geojson:Polygon",
    "Property": "ngsi-ld:Property",
    "Relationship": "ngsi-ld:Relationship",
    "Snapshot": "ngsi-ld:Snapshot",
    "SnapshotNotification": "ngsi-ld:SnapshotNotification",
    "Subscription": "ngsi-ld:Subscription",
    "TemporalProperty": "ngsi-ld:TemporalProperty",
    "Time": "ngsi-ld:Time",
    "VocabProperty": "ngsi-ld:VocabProperty",
    "accept": "ngsi-ld:accept",
    "aggrParams": "ngsi-ld:aggrParams",
    "aggrMethods": "ngsi-ld:aggrMethods",
    "aggrPeriodDuration": "ngsi-ld:aggrPeriodDuration",
    "attributeCount": "attributeCount",
    "attributeDetails": "attributeDetails",
    "attributeList": {
      "@id": "ngsi-ld:attributeList",
      "@type": "@vocab"
    },
    "attributeName": {
      "@id": "ngsi-ld:attributeName",
      "@type": "@vocab"
    },
    "attributeNames": {
      "@id": "ngsi-ld:attributeNames",
      "@type": "@vocab"
    },
    "attributeTypes": {
      "@id": "ngsi-ld:attributeTypes",
      "@type": "@vocab"
    },
    "attributes": {
      "@id": "ngsi-ld:attributes",
      "@type": "@vocab"
    },
    "attrs": "ngsi-ld:attrs",
    "avg": {
      "@id": "ngsi-ld:avg",
      "@container": "@list"
    },
    "bbox": {
      "@container": "@list",
      "@id": "geojson:bbox"
    },
    "cacheDuration": "ngsi-ld:cacheDuration",
    "collation": "ngsi-ld:collation",
    "containedBy": "ngsi-ld:isContainedBy",
    "contextSourceAlias": "ngsi-ld:contextSourceAlias",
    "contextSourceExtras": {
      "@id": "ngsi-ld:contextSourceExtras",
      "@type": "@json"
    },
    "contextSourceInfo": "ngsi-ld:contextSourceInfo",
    "contextSourceTimeAt": {
      "@id": "ngsi-ld:contextSourceTimeAt",
      "@type": "DateTime"
    }, 
    "contextSourceUptime": "ngsi-ld:contextSourceUptime",
    "cooldown": "ngsi-ld:cooldown",
    "coordinates": {
      "@container": "@list",
      "@id": "geojson:coordinates"
    },
    "createdAt": {
      "@id": "ngsi-ld:createdAt",
      "@type": "DateTime"
    },
    "csf": "ngsi-ld:csf",
"data": "ngsi-ld:data",
"dataset": {
"@id": "ngsi-ld:hasDataset",
      "@container": "@index"
},
"datasetId": {
"@id": "ngsi-ld:datasetId",
"@type": "@id"
    },
    "deletedAt": {
      "@id": "ngsi-ld:deletedAt",
      "@type": "DateTime"
    }, 
    "description": "http://purl.org/dc/terms/description",
    "detail": "ngsi-ld:detail",
    "distinctCount": {
      "@id": "ngsi-ld:distinctCount",
      "@container": "@list"
    },
    "endAt": {
      "@id": "ngsi-ld:endAt",
      "@type": "DateTime"
    },
    "endTimeAt": {
      "@id": "ngsi-ld:endTimeAt",
      "@type": "DateTime"
    },
    "endpoint": "ngsi-ld:endpoint",
    "entities": "ngsi-ld:entities",
    "entity": "ngsi-ld:entity",
    "entityCount": "ngsi-ld:entityCount",
    "entityId": {
      "@id": "ngsi-ld:entityId",
      "@type": "@id"
    },
    "entityList": {
      "@id": "ngsi-ld:entityList",
      "@container": "@list"
    },
    "entityMap": "ngsi-ld:hasEntityMap",
    "error": "ngsi-ld:error",
    "errors": "ngsi-ld:errors",
    "expandValues": "ngsi-ld:expandValues",
    "expiresAt": {
      "@id": "ngsi-ld:expiresAt",
      "@type": "DateTime"
    },
    "features": {
      "@container": "@set",
      "@id": "geojson:features"
    },
    "format": "ngsi-ld:format",
    "geoQ": "ngsi-ld:geoQ",
    "geometry": "geojson:geometry",
    "geoproperty": "ngsi-ld:geoproperty",
    "georel": "ngsi-ld:georel",
    "idPattern": "ngsi-ld:idPattern",
    "information": "ngsi-ld:information",
    "instanceId": {
      "@id": "ngsi-ld:instanceId",
      "@type": "@id"
    },
    "isActive": "ngsi-ld:isActive",
    "join": "ngsi-ld:join",
    "joinLevel": "ngsi-ld:hasJoinLevel",
    "json": {
      "@id": "ngsi-ld:hasJSON", "@type": "@json"
    },
    "jsonKeys": "ngsi-ld:jsonKeys",
    "jsons": {
      "@id": "ngsi-ld:jsons",
      "@container": "@list"
    },
    "key": "ngsi-ld:hasKey",
    "lang": "ngsi-ld:lang",
    "languageMap": {
      "@id": "ngsi-ld:hasLanguageMap",
      "@container": "@language"
    },
    "languageMaps": {
      "@id": "ngsi-ld:hasLanguageMaps",
      "@container": "@list"
    },
    "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
    "lastFailure": {
      "@id": "ngsi-ld:lastFailure",
      "@type": "DateTime"
    },
    "lastNotification": {
      "@id": "ngsi-ld:lastNotification",
      "@type": "DateTime"
    },
    "lastSuccess": {
      "@id": "ngsi-ld:lastSuccess",
      "@type": "DateTime"
    },
    "lastUsedAt": {
      "@id": "ngsi-ld:lastUsedAt",
      "@type": "DateTime"
    },
    "linkedMaps": "ngsi-ld:linkedMaps",
    "localOnly": "ngsi-ld:localOnly",
    "location": "ngsi-ld:location",
    "management": "ngsi-ld:management",
    "managementInterval": "ngsi-ld:managementInterval",
    "max": {
      "@id": "ngsi-ld:max",
      "@container": "@list"
    },
    "min": {
      "@id": "ngsi-ld:min",
      "@container": "@list"
    },
    "mode": "ngsi-ld:mode",
    "modifiedAt": {
      "@id": "ngsi-ld:modifiedAt",
      "@type": "DateTime"
    },
    "ngsildproof": {
      "@id": "ngsi-ld:ngsildproof",
      "@context": [{
        "entityIdSealed": "ngsi-ld:entityIdSealed",
        "entityTypeSealed": {
          "@id": "ngsi-ld:entityTypeSealed",
          "@type": "@vocab"
        }
      },
      "https://w3id.org/security/data-integrity/v2"
      ]
    },
    "notification": "ngsi-ld:notification",
    "notificationTrigger": "ngsi-ld:notificationTrigger",
    "notifiedAt": {
      "@id": "ngsi-ld:notifiedAt",
      "@type": "DateTime"
    },
    "notifierInfo": "ngsi-ld:notifierInfo",
    "notUpdated": "ngsi-ld:notUpdated",
    "object": {
      "@id": "ngsi-ld:hasObject",
      "@type": "@id"
    },
    "objectList": {
      "@id": "ngsi-ld:hasObjectList",
      "@container": "@list"
    },
    "objectLists": {
      "@id": "ngsi-ld:hasObjectLists",
      "@container": "@list"
    },
    "objects": {
      "@id": "ngsi-ld:hasObjects",
      "@container": "@list"
    },
    "objectType": {
      "@id": "ngsi-ld:hasObjectType",
      "@type": "@vocab"
    },
    "observationInterval": "ngsi-ld:observationInterval",
    "observationSpace": "ngsi-ld:observationSpace",
    "observedAt": {
      "@id": "ngsi-ld:observedAt",
      "@type": "DateTime"
    },
    "omit": "ngsi-ld:omit",
    "operations": "ngsi-ld:operations",
    "operationSpace": "ngsi-ld:operationSpace",
    "orderBy": {
      "@container": "@list",
      "@id": "ngsi-ld:orderBy"
    },
    "ordering": "ngsi-ld:ordering",
    "pick": "ngsi-ld:pick",
    "previousJson": {
      "@id": "ngsi-ld:hasPreviousJson",
      "@type": "@json"
    },
    "previousLanguageMap": {
      "@id": "ngsi-ld:hasPreviousLanguageMap",
      "@container": "@language"
    },
    "previousObject": {
      "@id": "ngsi-ld:hasPreviousObject",
      "@type": "@id"
    },
    "previousObjectList": {
      "@id": "ngsi-ld:hasPreviousObjectList",
      "@container": "@list"
    },
    "previousValue": "ngsi-ld:hasPreviousValue",
    "previousValueList": {
      "@id": "ngsi-ld:hasPreviousValueList",
      "@container": "@list"
    },
    "previousVocab": {
      "@id": "ngsi-ld:hasPreviousVocab",
      "@type": "@vocab"
    },
    "problemDetails": {
      "@id": "ngsi-ld:problemDetails",
      "@type": "@json"
    },
    "properties": "geojson:properties",
    "propertyNames": {
      "@id": "ngsi-ld:propertyNames",
      "@type": "@vocab"
    },
    "q": "ngsi-ld:q",
    "reason": "ngsi-ld:reason",
    "receiverInfo": "ngsi-ld:receiverInfo",
    "refreshRate": "ngsi-ld:refreshRate",
    "registrationId": "ngsi-ld:registrationId",
    "registrationName": "ngsi-ld:registrationName",
    "relationshipNames": {
      "@id": "ngsi-ld:relationshipNames",
      "@type": "@vocab"
},
    "resultStatus": "ngsi-ld:resultStatus",
"scope": "ngsi-ld:scope",
"scopeQ": "ngsi-ld:scopeQ",
"showChanges": "ngsi-ld:showChanges",
    "snapshotId": "ngsi-ld:snapshotId",
    "snapshotLifetime": "ngsi-ld:snapshotLifetime",
    "snapshotPriority": "ngsi-ld:snapshotPriority",
    "snapshotQueries": {
      "@id": "ngsi-ld:snapshotQueries",
      "@container": "@list"
    },
    "snapshotQueriesDetails": {
      "@id": "ngsi-ld:snapshotQueriesDetails",
      "@container": "@list"
    },
    "snapshotStatus": "ngsi-ld:snapshotStatus",
    "snapshotTemporalQueries": {
      "@id": "ngsi-ld:snapshotTemporalQueries",
      "@container": "@list"
    },
    "snapshotTemporalQueriesDetails": {
      "@id": "ngsi-ld:snapshotTemporalQueriesDetails",
      "@container": "@list"
    },
    "startAt": {
      "@id": "ngsi-ld:startAt",
      "@type": "DateTime"
    },
    "status": "ngsi-ld:status",
    "stddev": {
      "@id": "ngsi-ld:stddev",
      "@container": "@list"
    },
    "subscriptionId": {
      "@id": "ngsi-ld:subscriptionId",
      "@type": "@id"
    },
    "subscriptionName": "ngsi-ld:subscriptionName",
    "success": {
      "@id": "ngsi-ld:success",
      "@type": "@id"
    },
    "sum": {
      "@id": "ngsi-ld:sum",
      "@container": "@list"
    },
    "sumsq": {
      "@id": "ngsi-ld:sumsq",
      "@container": "@list"
    },
    "sysAttrs": "ngsi-ld:sysAttrs",
    "temporalQ": "ngsi-ld:temporalQ",
    "tenant": {
      "@id": "ngsi-ld:tenant",
      "@type": "@id"
    },
    "throttling": "ngsi-ld:throttling",
    "timeAt": {
      "@id": "ngsi-ld:timeAt",
      "@type": "DateTime"
    },
    "timeInterval": "ngsi-ld:timeInterval",
    "timeout": "ngsi-ld:timeout",
    "timeproperty": "ngsi-ld:timeproperty",
    "timerel": "ngsi-ld:timerel",
    "timesFailed": "ngsi-ld:timesFailed",
    "timesSent": "ngsi-ld:timesSent",
    "title": "http://purl.org/dc/terms/title",
    "totalCount": {
      "@id": "ngsi-ld:totalCount",
      "@container": "@list"
    },
    "triggerReason": "ngsi-ld:triggerReason",
    "typeList": {
      "@id": "ngsi-ld:typeList",
      "@type": "@vocab"
    },
    "typeName": {
      "@id": "ngsi-ld:typeName",
      "@type": "@vocab"
    },
    "typeNames": {
      "@id": "ngsi-ld:typeNames",
      "@type": "@vocab"
    },
    "unchanged": "ngsi-ld:unchanged",
    "unitCode": "ngsi-ld:unitCode",
    "updated": "ngsi-ld:updated",
    "uri": "ngsi-ld:uri",
    "value": "ngsi-ld:hasValue",
    "valueList": {
      "@id": "ngsi-ld:hasValueList",
      "@container": "@list"
    },
    "valueLists": {
      "@id": "ngsi-ld:hasValueLists",
      "@container": "@list"
    },
    "values": {
      "@id": "ngsi-ld:hasValues",
      "@container": "@list"
    },
    "valueType": {
      "@id": "ngsi-ld:hasValueType",
      "@type": "@vocab"
    },
    "vocab": {
      "@id": "ngsi-ld:hasVocab",
      "@type": "@vocab"
    },
    "vocabs": {
      "@id": "ngsi-ld:hasVocabs",
      "@container": "@list"
    },
    "watchedAttributes": {
      "@id": "ngsi-ld:watchedAttributes",
      "@type": "@vocab"
    },
    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/"
  }
}
```

>>> [!note] NOTE:

Implementers can take advantage of prefixed terms, i.e. in the form ngsi-ld:term, to provide a terser representation of the Core *\@context* .

>>>
+2908 −0

File added.

Preview size limit exceeded, changes collapsed.

+139 −0
Original line number Diff line number Diff line
# Annex D (informative): Transformation Algorithms

## D.1 Introduction

These algorithms are informative but NGSI-LD implementations should aim at either implementing them as they are described here or devising similar algorithms which take exactly the same input and provides exactly the same output (or an equivalent one as per the JSON-LD specification [n.2]).

## D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1)

This algorithm takes as input an NGSI-LD graph which top level node is a particular Entity and returns as output a JSON-LD document which represents all the data associated to the entity. The JSON-LD document (and its associated *\@context*) corresponds to a representation of the Entity in JSON-LD as per the NGSI-LD Information Model.

>>> [!note] NOTE:

An early implementation of this algorithm can be found at [i.5].

>>>

Let:

- **G** be a graph defined as follows:
  - Let **N** be G's top level node.
  - N is an Entity instance of type **T** or types **Ts**. Type name is "AliasT" or there is an Array of Type names ["AliasT1", ...,"AliasTn"], N's identifier is **I**.
  - N has 0 or more associated Property. Each Property (**Psi**) is defined as follows:
    - Property type identifier is **Pi**.
    - Property name is "AliasPi".
    - Property Value is **Vi**.
    - Property Value's associated data type is **Di**.

  

  - N is the subject of 0 or more Relationship. Each Relationship is defined as follows:
    - Relationship type identifier is **Ri**.
    - Relationship name is "AliasRi".
    - Relationship target object identifier is **Robji**.



- **O** be a JSON object initialized to the empty object ({}).
- **C** be a JSON-LD *\@context* initialized as described by annex B.

The algorithm should run as follows, provided all the preconditions defined above are satisfied:

1.  Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> ... <"AliasTn", Tn>.
2.  Add to O two new members:
    a.  <"id", I>.
    b.  <"type", "AliasT"> or <"type", ["AliasT1", ...,"AliasTn"]> .">.



3.  For each Property Psi (Pi, "AliasP", Vi, Di) associated to N:
    a.  Run Algorithm*ALG1.1*
        - Ps → Psi.
        - O → O.
        - C → C.



4.  For each Relationship Rs (Ri, AliasRi, Robji) associated to N:
    a.  Run Algorithm*ALG1.2*
        - Rs → Rsi.
        - O → O.
        - C → C.



5.  Return (O, C) and end of the algorithm.

## D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1)

Let **Ps** be the Property that has to be transformed. It is defined by (P, "AliasP", V, D), where **P** denotes a Property Type Id, "**AliasP**" is the Property name, **V** is the Property Value and **D** is the Property Value's data type.

Ps might be associated to extra Properties or Relationships.

Let O be the output JSON-LD object and C the associated JSON-LD context:

1.  Execute the following steps:
    a.  If no member with "AliasP" is present in O, add a new member to O with key "AliasP" and value an object structure, let it be named**Op**
        - <"type", "Property">.
        - If D is not a native JSON data type add a new member to Op with name "value" and which value has to be an object structure as follows:
          1.  <"@type", D>.
          2.  <"@value", V>.

        

        - Else If D is a native JSON data type add a new member to Op as follows:
          1.  <"value", V>.

    

    a.  Add a new member to C as follows:
        - <"AliasP", P>.

    

    a.  For each Property associated to Ps (Pss) recursively run the present algorithm (*ALG1.1*
        - Ps → Pss.
        - O → Op.
        - C → C.

    

    a.  For each Relationship associated to Ps (Rss) run algorithm*ALG1.2*
        - Rs → Rss.
        - O → Op.
        - C → C.



6.  Return (O,C) and end of the algorithm.

## D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2)

Let **Rs** be the Relationship that has to be transformed. It is defined by (R, "AliasR", Robj), where **R** denotes a Relationship Type Id, "**AliasR**" is the Relationship's name and **Robj** is the identifier of the target object of the Relationship.

Rs might be associated to extra Properties or Relationships.

Let O be the output JSON-LD object and C the current JSON-LD context:

1.  Execute the following statements:
    a.  If no member with "AliasR" is present in O, add a new member to O with key "AliasR" and value an object structure, let it be named**Or**
        - <"object", Robj>.
        - <"type", "Relationship">.

    

    a.  For each Property associated to Rs (Pss) run the algorithm*ALG1.1*
        - Ps → Pss.
        - O → Or.
        - C → C.

    

    a.  For each Relationship associated to Rs (Rss) recursively run the present algorithm*ALG1.2*
        - Rs → Rss.
        - O → Or.
        - C → C.



7.  Return (O,C) and end of the algorithm.
Loading