Commit 689f92fb authored by Marco Cavalli's avatar Marco Cavalli
Browse files

feat: added editor notes

chore: editorial changes
parent f039d35a
Loading
Loading
Loading
Loading
+1 −1
Original line number Diff line number Diff line
# Annex E [(informative)]{.inform}: RDF-compatible specification of NGSI-LD meta-model

The content of this annex is now in ETSI GS CIM 006 [i.6].
The content of this annex is now in ETSI TS 104 178 [i.6].
+6 −6
Original line number Diff line number Diff line
# 1 Scope

The present document defines a standardized API for Context Information
Management (NGSI-LD API) enabling close to real-time (right-time) access to
context/digital twin information coming from many different sources (not only
The present document defines a standardized API for context information
management (NGSI-LD API) enabling close to real-time (right-time) access to
context information/digital twins coming from many different sources (not only
IoT data sources). The present document defines how such an API enables
applications to perform updates on context, register context providers which can
applications to perform updates on context, register context sources which can
be queried to get updates on context, query information on current and historic
context information and subscribe to receive notifications of context changes.
The criteria for choice of the API characteristics are based on requirements
resulting from the Use Cases ETSI GR CIM 002 [i.4] and other work items ETSI GR
CIM 007 [i.5] and ETSI GS CIM 006 [i.6] on security and on the information
model. The present document supersedes prior versions, including ETSI CIM 009
CIM 007 [i.5] (security) and ETSI TS 104 178 [i.6] (information
model). The present document supersedes prior versions, including ETSI CIM 009
[i.7] and ETSI GS CIM 004 [i.8].
+6 −4
Original line number Diff line number Diff line
@@ -44,7 +44,7 @@ present document.

[n.8] W3C<sup>®</sup> Recommendation 16 July 2020: "[JSON-LD 1.1 - A JSON-based Serialization for Linked Data](http://www.w3.org/TR/json-ld/)".

[n.9] [ETSI GS CIM 019](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/019/): "cross-cutting Context Information Management (CIM); handling of provenance information in NGSI-LD".
[n.9] ETSI TS 104 179: "Data Solutions (DATA); NGSI-LD Provenance and Integrity".

[n.10] [Codes for Units of Measure used in International Trade Revision 9](http://www.unece.org/fileadmin/DAM/cefact/recommendations/rec20/rec20_Rev9e_2014.xls).

@@ -101,6 +101,8 @@ conformance to the present document.

<!-- prettier-ignore-start -->

<mark>Editor Note: Remove [i.1] (referenced it in the Introduction clause) and renumber all the remaining</mark>

::: REFS
[i.1] ETSI ISG CIM: "[NGSI-LD Status](https://docbox.etsi.org/ISG/CIM/Open/NGSI-LD%20Status.pdf)".

@@ -114,13 +116,13 @@ conformance to the present document.

[i.6] ETSI TS 104 178: "Data Solutions (DATA); NGSI-LD Information Model".

[i.7] [ETSI GS CIM 009](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/): "Context Information Management (CIM); NGSI-LD API".
[i.7] [ETSI GS CIM 009 (V1.9.1)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/009/01.09.01_60/gs_cim009v010901p.pdf): "Context Information Management (CIM); NGSI-LD API".

[i.8] ETSI GS CIM 004 (V1.1.2): "Context Information Management (CIM); Application Programming Interface (API)".
[i.8] [ETSI GS CIM 004 (V1.1.2)](https://www.etsi.org/deliver/etsi_gs/CIM/001_099/004/01.01.02_60/gs_cim004v010102p.pdf): "Context Information Management (CIM); Application Programming Interface (API)".

[i.9] Graph Databases: "New Opportunities for Connected Data". O'Reilly 2<sup>nd</sup> Edition. Webber, Robinson, et al. ISBN:1491930896 9781491930892.

[i.10] ETSI TS 103 264 (V3.1.1): "SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping".
[i.10] [ETSI TS 103 264 (V4.1.1)](https://www.etsi.org/deliver/etsi_ts/103200_103299/103264/04.01.01_60/ts_103264v040101p.pdf): "SmartM2M; Smart Applications; Reference Ontology and oneM2M Mapping".

[i.11] W3C<sup>®</sup> Recommendation 25 February 2014: "[RDF Schema 1.1](https://www.w3.org/TR/2014/REC-rdf-schema-20140225/)".

+12 −26
Original line number Diff line number Diff line
@@ -34,7 +34,7 @@ Relationship names to the following ABNF grammar:
```text
nameChar = unicodeNumber / unicodeLetter
nameChar =/ %x5F           ; _
nameChar =/ %x5F                         ; Representing the underscore character _
name = unicodeLetter *nameChar
```
@@ -2285,11 +2285,8 @@ Table: Additional members of the Subscription data type
| Name        | Data Type   | Restrictions              | Cardinality | Description                                                                    |
+=============+=============+===========================+=============+================================================================================+
| status      | String      | Allowed values:           | 0..1        | Read-only. Provided by the system when querying the details of a subscription. |
|             |             |                           |             |                                                                                |
|             |             | ["active"]{.HTML-Code}    |             |                                                                                |
|             |             |                           |             |                                                                                |
|             |             | ["paused"]{.HTML-Code}    |             |                                                                                |
|             |             |                           |             |                                                                                |
|             |             | ["active"]{.HTML-Code},   |             |                                                                                |
|             |             | ["paused"]{.HTML-Code},   |             |                                                                                |
|             |             | ["expired"]{.HTML-Code}   |             |                                                                                |
+-------------+-------------+---------------------------+-------------+--------------------------------------------------------------------------------+
:::
@@ -2508,12 +2505,9 @@ Table: Output only members of the Snapshot data type
+--------------------------------+----------------------------+--------------------------------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name                           | Data Type                  | Restrictions                                                 | Cardinality | Description                                                                                                                                            |
+================================+============================+==============================================================+=============+========================================================================================================================================================+
| snapshotStatus                 | String                     | *It shall be one of:*                                        | 1           | Allows clients to check the status of the Snapshot.                                                                                                    |
|                                |                            |                                                              |             |                                                                                                                                                        |
| snapshotStatus                 | String                     | It shall be one of:                                          | 1           | Allows clients to check the status of the Snapshot.                                                                                                    |
|                                |                            | ["preparing","success","partial",]{.HTML-Code}               |             |                                                                                                                                                        |
|                                |                            |                                                              |             |                                                                                                                                                        |
|                                |                            | ["failure"]{.HTML-Code}                                      |             |                                                                                                                                                        |
|                                |                            |                                                              |             |                                                                                                                                                        |
|                                |                            | or ["empty"]{.HTML-Code}                                     |             |                                                                                                                                                        |
|                                |                            |                                                              |             |                                                                                                                                                        |
|                                |                            | *The initial status shall be* ["preparing"]{.HTML-Code}*.    |             |                                                                                                                                                        |
@@ -2665,11 +2659,8 @@ Table: Endpoint data type definition
| uri          | String           | Dereferenceable URI                    | 1           | URI which conveys the endpoint which will receive the notification.                                                                                                                                                                                                      |
+--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| accept       | String           | MIME type. It shall be one of:         | 0..1        | Intended to convey the MIME type of the notification payload body (JSON, or JSON-LD, or GeoJSON). If not present, default is ["application/json"]{.HTML-Code}.                                                                                                           |
|              |                  |                                        |             |                                                                                                                                                                                                                                                                          |
|              |                  | ["application/json"]{.HTML-Code}       |             |                                                                                                                                                                                                                                                                          |
|              |                  |                                        |             |                                                                                                                                                                                                                                                                          |
|              |                  | ["application/ld+json"]{.HTML-Code}    |             |                                                                                                                                                                                                                                                                          |
|              |                  |                                        |             |                                                                                                                                                                                                                                                                          |
|              |                  | ["application/json"]{.HTML-Code},      |             |                                                                                                                                                                                                                                                                          |
|              |                  | ["application/ld+json"]{.HTML-Code},   |             |                                                                                                                                                                                                                                                                          |
|              |                  | ["application/geo+json"]{.HTML-Code}   |             |                                                                                                                                                                                                                                                                          |
+--------------+------------------+----------------------------------------+-------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| cooldown     | Number           | Greater than 0                         | 0..1        | Once a failure has occurred, minimum period of time in milliseconds which shall elapse before attempting to make a subsequent notification to the same endpoint after failure. If requests are received before the cooldown period has expired, no notification is sent. |
@@ -3180,12 +3171,9 @@ Table: ExecutionResult data type definition
+================+=============+=============================================+=============+========================================================================================================================================================================================+
| problemDetails | JSON        | ProblemDetails (see IETF RFC 7807 [n.6])    | 0..1        | Provides more details regarding the result status, especially when reporting an error.                                                                                                 |
+----------------+-------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| resultStatus   | String      | *It shall be one of:*                       | 1           | Describes the status of the result. ["failure"]{.HTML-Code}, if an error is reported, ["success"]{.HTML-Code} in case of a non-empty result and ["empty"]{.HTML-Code} otherwise.       |
|                |             |                                             |             |                                                                                                                                                                                        |
|                |             | ["success",]{.HTML-Code}                    |             |                                                                                                                                                                                        |
|                |             |                                             |             |                                                                                                                                                                                        |
|                |             | ["failure"]{.HTML-Code}                     |             |                                                                                                                                                                                        |
|                |             |                                             |             |                                                                                                                                                                                        |
| resultStatus   | String      | It shall be one of:                         | 1           | Describes the status of the result. ["failure"]{.HTML-Code}, if an error is reported, ["success"]{.HTML-Code} in case of a non-empty result and ["empty"]{.HTML-Code} otherwise.       |
|                |             | ["success"]{.HTML-Code},                    |             |                                                                                                                                                                                        |
|                |             | ["failure"]{.HTML-Code},                    |             |                                                                                                                                                                                        |
|                |             | or ["empty"]{.HTML-Code}                    |             |                                                                                                                                                                                        |
+----------------+-------------+---------------------------------------------+-------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
:::
@@ -3360,12 +3348,10 @@ Table: SnapshotNotification data type definition
+--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| snapshotQueriesDetails         | ExecutionResultDetails[]   | _List of ExecutionResultDetails_ (Clause+++root.2.6.8.3)    | 0..1        | List with one result per Snapshot query execution, in the same order as Snapshot queries.                                                                                                                                   |
+--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| snapshotStatus                 | String                     | *It shall be one of:*                                       | 1           | Indicates the status of the Snapshot, enabling the user to decide whether the snapshot is ready for querying.                                                                                                               |
|                                |                            |                                                             |             |                                                                                                                                                                                                                             |
|                                |                            | ["success","partial",]{.HTML-Code}                          |             |                                                                                                                                                                                                                             |
|                                |                            |                                                             |             |                                                                                                                                                                                                                             |
| snapshotStatus                 | String                     | It shall be one of:                                         | 1           | Indicates the status of the Snapshot, enabling the user to decide whether the snapshot is ready for querying.                                                                                                               |
|                                |                            | ["success"]{.HTML-Code},                                    |             |                                                                                                                                                                                                                             |
|                                |                            | ["partial"]{.HTML-Code},                                    |             |                                                                                                                                                                                                                             |
|                                |                            | ["failure"]{.HTML-Code}                                     |             |                                                                                                                                                                                                                             |
|                                |                            |                                                             |             |                                                                                                                                                                                                                             |
|                                |                            | or ["empty"]{.HTML-Code}                                    |             |                                                                                                                                                                                                                             |
+--------------------------------+----------------------------+-------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| temporalSnapshotQueriesDetails | ExecutionResultDetails[]   | _List of ExecutionResultDetails_ (Clause+++root.2.6.8.3)    | 0..1        | List with one result per temporal Snapshot query execution, in the same order as temporal Snapshot queries.                                                                                                                 |
+1 −1
Original line number Diff line number Diff line
# Executive summary

The present document formally describes the Context Information Management API (NGSI-LD) Specification. The Context Information Management API allows users to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders. Context information is modelled as attributes (properties and relationships) of context entities, also referred to as "digital twins", representing real-world assets. It enables close to real-time access to information coming from many different sources (not only IoT data sources).
The present document formally describes the NGSI-LD API Specification. The NGSI-LD API allows users to provide, consume and subscribe to context information in multiple scenarios and involving multiple stakeholders. Context information is modelled as attributes (properties and relationships) of context entities, also referred to as "digital twins", representing real-world assets. It enables close to real-time access to information coming from many different sources (not only IoT data sources).
Loading