diff --git a/md/clause-5.md b/md/clause-5.md index c3df0a831f7d289e069a5482084640339cac507b..743799eccf515f87b07dbc946c3d65b6154ead12 100644 --- a/md/clause-5.md +++ b/md/clause-5.md @@ -2337,24 +2337,45 @@ Table: Subscription data type definition | | | ["attributeUpdated"]{.HTML-Code}, ["attributeDeleted"]{.HTML-Code} | | and ["attributeUpdated"]{.HTML-Code}. ["entityUpdated"]{.HTML-Code} is equivalent to | | | | | | the combination ["attributeCreated"]{.HTML-Code}, ["attributeUpdated"]{.HTML-Code} | | | | | | and ["attributeDeleted"]{.HTML-Code}. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | watchedAttributes | String[] | Attribute name as short hand strings or URIs. Empty array (0 length) is not allowed. | 0..1 | Watched Attributes (Properties or Relationships). If not defined it means any Attribute. | | | | | | | | | | if _`timeInterval`_ is present it shall not appear (0 cardinality) | | | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | q | String | A valid query string as per Clause+++clause-7+++7.2.3 | 0..1 | Query that shall be met by subscribed entities in order to trigger the notification. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | geoQ | GeoParams | See data type definition in Clause+++root.2.6.7.2 | 0..1 | Geoquery that shall be met by subscribed entities in order to trigger the notification. | +| | | | | | +| | | | | This parameter is matched against the specified Context Source Registration GeoJSON attributes,| +| | | | | e.g. _`location`_, _`observationSpace`_ or _`operationSpace`_, if the Subscription data type | +| | | | | is used for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | scopeQ | String | See Clause+++clause-7+++7.2.5 | 0..1 | Scope query. | +| | | | | | +| | | | | This parameter is matched against the Context Source Registration's scope attribute, if the | +| | | | | Subscription data type is used for a Context Source Registration Subscription as described in | +| | | | | clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ -| temporalQ | TemporalParams | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be used **only** in *Context Registration Subscriptions* | +| temporalQ | TemporalParams | See data type definition in Clause+++root.2.6.7.4 | 0..1 | Temporal Query to be used **only** in *Context Source Registration Subscriptions* | | | | | | for matching [Context Source Registrations]{.HTML-Keyboard} of | | | | | | [Context Sources]{.HTML-Keyboard} providing temporal information. | +| | | | | In this case, it is matched against the relevant time interval, i.e. | +| | | | | _`observationInterval`_, if the temporal attribute of interest is _`observedAt`_, or | +| | | | | _`managementInterval`_, if the temporal attribute of interest is _`createdAt`_ or | +| | | | | _`modifiedAt`_. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | csf | String | A valid query string as per Clause+++clause-7+++7.2.3 | 0..1 | Context source filter that shall be met by [Context Source Registrations]{.HTML-Keyboard} | | | | | | describing [Context Sources]{.HTML-Keyboard} to be used for Entity Subscriptions. | | | | | | | +| | | | | This parameter is matched against the Context Source Registration attributes, if the | +| | | | | Subscription data type is used for a Context Source Registration Subscription as described in | +| | | | | clause 12.4. In other cases it is ignored. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | datasetId | String[] | Valid URIs,["@none"]{.HTML-Code} for including the default Attribute instances. | 0..1 | Specifies the datasetIds of the Attribute instances to be selected for each matched | | | | | | Attribute as per Clause+++clause-8+++8.5. | @@ -2363,6 +2384,9 @@ Table: Subscription data type definition +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | expandValues | String | Comma separated list of attribute names | 0..1 | Values of the identified attributes should be expanded against | | | | | | the supplied _`@context`_ using JSON-LD type coercion prior to executing the query. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | expiresAt | String | _DateTime_ (Clause+++root.2.2.4) | 0..1 | Expiration date for the subscription. | | | | | | | @@ -2376,6 +2400,9 @@ Table: Subscription data type definition | jsonKeys | String | Comma separate list of attribute names | 0..1 | Values of the identified attributes are to be considered uninterpretable as JSON-LD | | | | | | and should not be expanded against the supplied | | | | | | _`@context`_ using JSON-LD type coercion prior to executing the query. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | jsonldContext | String | Dereferenceable URI | 0..1 | The dereferenceable URI of the JSON-LD _`@context`_ to be used when sending a notification | | | | | | resulting from the subscription. | @@ -2383,10 +2410,16 @@ Table: Subscription data type definition +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | lang | String | A natural language filter in the form of a IETF RFC 5646 [n.11] language code | 0..1 | Language filter to be applied to the query (Clause+++clause-7+++7.2.7). | | | | | | | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | localOnly | Boolean | | 0..1 | If _`localOnly=true`_ then the subscription only pertains to the Entities stored locally. | | | | | | In case the Subscription pertains to a Snapshot it is always local, regardless of whether | | | | | | _`localOnly`_ is set to _`true`_ or not. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | ngsildConformance | String | A semantically versioned string in the form *major.minor*, which conforms to a version of the NGSI-LD specification | 0..1 | If provided the notification shall undergo a backwards compatibility | | | | | | operation as defined by Clause+++clause-9+++9.5.3 and be amended to conform to the | @@ -2395,9 +2428,11 @@ Table: Subscription data type definition | splitEntities | Boolean | default decided by implementation; it should be configurable. The parameter does not apply in case | 0..1 | If _`true`_ it is assumed that single Entities are distributed between different | | | | _`localOnly`_ is _`true`_ . | | Context Brokers and/or Context Sources and this has to be taken into account when a | | | | | | applying any kind of filters (_`q`_, _`geoQ`_, _`scopeQ`_, Attributes etc.). If _`false`_ | -| | | | | it is expected that Context Broker and/or Context Source always have complete | -| | | | | Entities, which allows applying filters locally. | +| | | This parameter is not applicable if the Subscription data type is used for a Context Source Registration Subscription as | | it is expected that Context Broker and/or Context Source always have complete | +| | | described in clause 12.4. | | Entities, which allows applying filters locally. | | | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | subscriptionName | String | | 0..1 | A (short) name given to this Subscription. | | | | | | | @@ -2405,11 +2440,15 @@ Table: Subscription data type definition +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | throttling | Number | Greater than 0. Fractional values are allowed. If _`timeInterval`_ is present it shall not appear (0 cardinality) | 0..1 | Minimal period of time in seconds which shall elapse between two consecutive notifications. | | | | | | | -| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Subscription data type is used | +| | | | | for a Context Source Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ | timeInterval | Number | Greater than 0 | 0..1 | Indicates that a notification shall be delivered periodically regardless of attribute | | | | | | changes. Actually, when the time interval (in seconds) specified in this value field | | | | if _`watchedAttributes`_ is present it shall not appear (0 cardinality) | | is reached. | +| | | | | | +| | | | | This parameter is not applicable if the Subscription data type is used for a Context Source | +| | | | | Registration Subscription as described in clause 12.4. | +---------------------+--------------------+----------------------------------------------------------------------------------------------------------------------------+--------------+------------------------------------------------------------------------------------------------+ ::: @@ -3080,12 +3119,18 @@ Table: NotificationParams data type definition | | | | | Attribute names to be included in the notification payload body. If undefined it will mean all Attributes. | +-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | format | String | It shall be one of: ["normalized"]{.HTML-Code}, ["concise"]{.HTML-Code}, ["simplified"]{.HTML-Code} (or its synonym ["keyValues"]{.HTML-Code}) | 0..1 | Conveys the representation format of the entities delivered at notification time. By default, it will be in the normalized format. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Notification is used as part of a Context Source Registration Subscription as described in clause 12.4. | +-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | join | String | It shall be one of: ["flat"]{.HTML-Code}, ["inline"]{.HTML-Code}, ["@none"]{.HTML-Code} | 0..1 | String representing the type of [Linked Entity]{.HTML-Keyboard} retrieval to apply. | | | | | | | | | | | | By default, it will be ["@none"]{.HTML-Code}. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Notification is used as part of a Context Source Registration Subscription as described in clause 12.4. | +-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | joinLevel | Number | Positive Integer | 0..1 | Depth of [Linked Entity]{.HTML-Keyboard} retrieval to apply. Default is 1. Only applicable if _`join`_ parameter is ["flat"]{.HTML-Code}, or ["inline"]{.HTML-Code}. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Notification is used as part of a Context Source Registration Subscription as described in clause 12.4. | +-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | omit | String[] | Entity member (["id"]{.HTML-Code}, ["type"]{.HTML-Code}, ["scope"]{.HTML-Code} or a projected Attribute name) as a valid attribute projection language string as per Clause+++clause-7+++7.3.2. | 0..1 | When defined, the specified Entity members are removed from each Entity within the payload. | | | | Empty array (0 length) is not allowed | | | @@ -3098,10 +3143,14 @@ Table: NotificationParams data type definition | | | | | modifications and deletions, but not in the case of creations. | | | | | | | | | | | | _`showChanges`_ cannot be _`true`_ in case format is ["keyValues"]{.HTML-Code}. | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Notification is used as part of a Context Source Registration Subscription as described in clause 12.4. | +-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | sysAttrs | Boolean | _`false`_ by default | 0..1 | If _`true`_, the system generated attributes _`createdAt`_ and _`modifiedAt`_ and the system attribute _`expiresAt`_ are included in the response payload body, | | | | | | in the case of a deletion also _`deletedAt`_. | | | | | | | +| | | | | | +| | | | | This parameter is not applicable and shall be ignored if the Notification is used as part of a Context Source Registration Subscription as described in clause 12.4. | +-------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ :::