Run prettier (c8e14688) · Commits · DATA - Data Solutions / Specifications / TS 104 175

md/clause-10.md

+191 −140

File changed.

Preview size limit exceeded, changes collapsed.

md/clause-11.md

+62 −51

Original line number	Diff line number	Diff line
		@@ -560,15 +560,16 @@ Figure: Retrieve Temporal Evolution of an Entity use case
		(optional).
		- An NGSI-LD temporal query as mandated by Clause+++clause-7+++root.2.6
		(optional).
		- A parameter (_`lastN`_) conveying that only the last N instances (per Attribute)
		within the concerned temporal interval shall be retrieved (optional).
		- An optional JSON-LD context.
		- A flag indicating whether to return the location of the [Entity Map]{.HTML-Keyboard} used within
		the operation (optional).
		- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity Map]{.HTML-Keyboard} is to be created
		- A parameter (_`lastN`_) conveying that only the last N instances (per
		Attribute) within the concerned temporal interval shall be retrieved
		(optional).
		- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching Entity
		registrations (optional).
		- An optional JSON-LD context.
		- A flag indicating whether to return the location of the [Entity
		Map]{.HTML-Keyboard} used within the operation (optional).
		- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity
		Map]{.HTML-Keyboard} is to be created (optional).
		- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching
		Entity registrations (optional).
		- A _`datasetId`_ parameter that specifies which Attribute instances are to be
		selected as defined by Clause+++clause-8+++root.5 (optional).

		@@ -576,9 +577,9 @@ Figure: Retrieve Temporal Evolution of an Entity use case

		- If the Entity ID is not present or it is not a valid URI, then an error of
		type [BadRequestData]{.HTML-Error} shall be raised.
		- If projection attributes are present and indicate the use of [Linked Entity]{.HTML-Keyboard}
		retrieval, an error of type [BadRequestData]{.HTML-Error}
		shall be raised.
		- If projection attributes are present and indicate the use of [Linked
		Entity]{.HTML-Keyboard} retrieval, an error of type
		[BadRequestData]{.HTML-Error} shall be raised.
		- If the NGSI-LD endpoint does not know about the target Entity, because there
		is no existing Entity whose id (URI) is equivalent held locally, and no
		matching registrations apply, then an error of type
		@@ -600,22 +601,25 @@ Figure: Retrieve Temporal Evolution of an Entity use case
		Attributes of an Entity, does not include data corresponding to the temporal
		query interval, then such Entity shall be removed from S, thus it shall not
		appear in the final result set. Let S1 be this new subset.
		- If the ContextBroker implementation supports the use of [Entity Maps]{.HTML-Keyboard} then:
		- If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching Entity
		registrations is present it shall be retrieved:
		- If the resource cannot be found, or the data has expired, a new [Entity Map]{.HTML-Keyboard}
		shall be created.
		- If the ContextBroker implementation supports the use of [Entity
		Maps]{.HTML-Keyboard} then:
		- If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of
		matching Entity registrations is present it shall be retrieved:
		- If the resource cannot be found, or the data has expired, a new [Entity
		Map]{.HTML-Keyboard} shall be created.
		- If the data has not expired, only the retrieved Entity Map shall be
		used to determine which [Context Source Registrations]{.HTML-Keyboard}
		match the Entity ID.
		- If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the request, and no
		[Entity Map]{.HTML-Keyboard} currently exists, then a new [Entity Map]{.HTML-Keyboard} shall be created.
		- If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the
		request, and no [Entity Map]{.HTML-Keyboard} currently exists, then a new
		[Entity Map]{.HTML-Keyboard} shall be created.
		- For [Context Source Registrations]{.HTML-Keyboard} that match the Entity ID
		and support the "retrieveTemporal" operation (see operations and operation
		groups in Clause+++clause-9+++root.2), implementations shall do the following:
		- If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an [Entity Map]{.HTML-Keyboard} entry linked
		to a [Context Source Registration]{.HTML-Keyboard} is found, the location of
		the linked [Entity Map]{.HTML-Keyboard} shall be passed as part of any forwarded request.
		- If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an
		[Entity Map]{.HTML-Keyboard} entry linked to a [Context Source
		Registration]{.HTML-Keyboard} is found, the location of the linked [Entity
		Map]{.HTML-Keyboard} shall be passed as part of any forwarded request.
		- For any exclusive, redirect and inclusive [Context
		Source]{.HTML-Keyboard}, the request is forwarded for remote retrieval by
		matching endpoints. and remote Attribute data for the Entity is received.
		@@ -626,9 +630,10 @@ Figure: Retrieve Temporal Evolution of an Entity use case
		instance, whose value of the _`timeproperty`_, which is used for the
		temporal query (_`observedAt`_ as default), is not present in any of the
		Attribute instances received from elsewhere.
		- If an [Entity Map]{.HTML-Keyboard} is in use for this operation, the [Entity Map]{.HTML-Keyboard}'s linked maps
		are updated to hold the location of every [Entity Map]{.HTML-Keyboard} used by the [Context
		Source Registrations.]{.HTML-Keyboard}
		- If an [Entity Map]{.HTML-Keyboard} is in use for this operation, the [Entity
		Map]{.HTML-Keyboard}'s linked maps are updated to hold the location of every
		[Entity Map]{.HTML-Keyboard} used by the [Context Source
		Registrations.]{.HTML-Keyboard}
		- For the set of [Attribute Instances]{.HTML-Keyboard} that are in S1, when )
		_`datasetId`_ parameter is provided in the request:
		- Filter the Attribute instances based on the _`datasetId`_ parameter, i.e.
		@@ -638,9 +643,10 @@ Figure: Retrieve Temporal Evolution of an Entity use case
		- If there is no Attribute instance whose _`datasetId`_ matches the value of
		the parameter, remove the complete Attribute from S1.
		- From the set of [Attribute Instances]{.HTML-Keyboard} that are in S1, include
		in their temporal representation only the Attribute instances (up to _`lastN`_)
		corresponding to the query's projection Attributes, or aggregated values of
		Attribute instances (if aggregated temporal representation is requested).
		in their temporal representation only the Attribute instances (up to
		_`lastN`_) corresponding to the query's projection Attributes, or aggregated
		values of Attribute instances (if aggregated temporal representation is
		requested).

		In the general case, it is not possible to retrieve a set of entities by only
		specifying desired Entity identifiers, without further specifying restrictions
		@@ -723,12 +729,12 @@ Figure: Query Temporal Evolution of Entities use case
		- A specified language filter as per Clause+++clause-7+++root.2.7 (optional).
		- A list (one or more) of Attribute names whose values shall be expanded to URIs
		prior to executing a query (optional).
		- A flag indicating whether to return the location of the [Entity Map]{.HTML-Keyboard} used within
		the operation (optional).
		- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity Map]{.HTML-Keyboard} is to be created
		(optional).
		- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching Entity
		registrations (optional).
		- A flag indicating whether to return the location of the [Entity
		Map]{.HTML-Keyboard} used within the operation (optional).
		- A suggested lifetime for the [Entity Map]{.HTML-Keyboard}, if [Entity
		Map]{.HTML-Keyboard} is to be created (optional).
		- The location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching
		Entity registrations (optional).
		- A _`datasetId`_ parameter that specifies which Attribute instances are to be
		selected as defined by Clause+++clause-8+++root.5 (optional).
		- A preferred ordering of Entities retrieved - only the Entity member name
		@@ -755,7 +761,8 @@ Clause+++clause-8+++root.6 ), no further restrictions have to be provided.
		Attribute; c. NGSI-LD Query, including at least one non-system Attribute; d.
		NGSI-LD GeoQuery; e. local scope (see Clause+++clause-8+++root.6).

		If none of the above is provided, then an error of type [BadRequestData]{.HTML-Error}
		If none of the above is provided, then an error of type
		[BadRequestData]{.HTML-Error}

		- If projection attributes or filter conditions indicate the use of [Linked
		Entity ]{.HTML-Keyboard} retrieval, an error of type
		@@ -844,22 +851,26 @@ Clause+++clause-8+++root.6 ), no further restrictions have to be provided.
		S4 be the new subset.
		- If no Scope query is provided, then S4 is equal to S3.

		- If the ContextBroker implementation supports the use of [Entity Maps]{.HTML-Keyboard} then:
		- If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of matching Entity
		registrations is present it shall be retrieved:
		- If the resource cannot be found, or the data has expired, a new [Entity Map]{.HTML-Keyboard}
		shall be created.
		- If the data has not expired, only the retrieved [Entity Map]{.HTML-Keyboard} shall be used to
		determine which Context Source Registrations match the Entity ID.
		- If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the request, and no
		[Entity Map]{.HTML-Keyboard} currently exists, then a new [Entity Map]{.HTML-Keyboard} shall be created.
		- If the ContextBroker implementation supports the use of [Entity
		Maps]{.HTML-Keyboard} then:
		- If the location of a resource holding an [Entity Map]{.HTML-Keyboard} of
		matching Entity registrations is present it shall be retrieved:
		- If the resource cannot be found, or the data has expired, a new [Entity
		Map]{.HTML-Keyboard} shall be created.
		- If the data has not expired, only the retrieved [Entity
		Map]{.HTML-Keyboard} shall be used to determine which Context Source
		Registrations match the Entity ID.
		- If a flag to return an [Entity Map]{.HTML-Keyboard} was present in the
		request, and no [Entity Map]{.HTML-Keyboard} currently exists, then a new
		[Entity Map]{.HTML-Keyboard} shall be created.
		- Unless local scope is specified (see Clause+++clause-8+++root.6), for [Context
		Source Registrations]{.HTML-Keyboard} that match the query and support the
		"queryTemporal" operation (see operations and operation groups in
		Clause+++clause-9+++root.2), implementations shall do the following:
		- If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an [Entity Map]{.HTML-Keyboard} entry linked
		to a Context Source Registration is found, the location of the [Entity Map]{.HTML-Keyboard}
		shall be passed as part of the forwarded request.
		- If an [Entity Map]{.HTML-Keyboard} is in use for this operation, and an
		[Entity Map]{.HTML-Keyboard} entry linked to a Context Source Registration
		is found, the location of the [Entity Map]{.HTML-Keyboard} shall be passed
		as part of the forwarded request.
		- If split entities flag is explicitly set to true or, if not explicitly
		set, the default setting of the deployment allows split entities, the
		filters (filter conditions specified by the query, geospatial restrictions
		@@ -903,9 +914,9 @@ Clause+++clause-8+++root.6 ), no further restrictions have to be provided.
		- If a _`datasetId`_ parameter is provided, from S7, for all Entities, filter
		the Attribute instances based on the _datasetIds_ specified in the parameter,
		i.e. keep only the Attribute instances whose _`datasetId`_ is specified. The
		default Attribute instance is matched, if ["@none"]{.HTML-Code} is specified.
		Remove all Attributes without remaining Attribute instances. Let S8 be this
		new subset.
		default Attribute instance is matched, if ["@none"]{.HTML-Code} is
		specified. Remove all Attributes without remaining Attribute instances. Let S8
		be this new subset.
		- If no _`datasetId`_ is provided then S8 equals to S7.
		- From the set of Entities that are in S8, include in their temporal
		representation only the Attribute instances (up to _lastN_) corresponding to

md/clause-12.md

+52 −47

Original line number	Diff line number	Diff line
		@@ -3,14 +3,16 @@
		## 12.1 Introduction

		Clause+++root describes all operations related to the Registry API. It allows
		for registering [Context Sources]{.HTML-Keyboard} and managment of [Context Source Registrations]{.HTML-Keyboard}.
		for registering [Context Sources]{.HTML-Keyboard} and managment of [Context
		Source Registrations]{.HTML-Keyboard}.

		## 12.2 Context Source Registration

		### 12.2.1 Introduction

		This clause defines all operations that [Context Broker]{.HTML-Keyboard} implementations shall
		offer to ensure the discovery, operation and management of [Context Sources]{.HTML-Keyboard}.
		This clause defines all operations that [Context Broker]{.HTML-Keyboard}
		implementations shall offer to ensure the discovery, operation and management of
		[Context Sources]{.HTML-Keyboard}.

		### 12.2.2 Register Context Source

		@@ -20,8 +22,8 @@ This operation allows registering a context source within an NGSI-LD system.

		#### 12.2.2.2 Use case diagram

		A [Context Provider]{.HTML-Keyboard} can register one or more [Context Sources]{.HTML-Keyboard} within an NGSI-LD
		system as shown in Figure+++below.
		A [Context Provider]{.HTML-Keyboard} can register one or more [Context
		Sources]{.HTML-Keyboard} within an NGSI-LD system as shown in Figure+++below.

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

		@@ -116,8 +118,8 @@ in an NGSI-LD system.

		#### 12.2.3.2 Use case diagram

		A [Context Provider]{.HTML-Keyboard} can update a [Context Source Registration]{.HTML-Keyboard}
		in an NGSI-LD system as shown in Figure+++below.
		A [Context Provider]{.HTML-Keyboard} can update a [Context Source
		Registration]{.HTML-Keyboard} in an NGSI-LD system as shown in Figure+++below.

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

		@@ -203,8 +205,8 @@ from an NGSI-LD system.

		#### 12.2.4.2 Use case diagram

		A [Context Provider]{.HTML-Keyboard} can delete a [Context Source Registration]{.HTML-Keyboard} from an NGSI-LD
		system as shown in Figure+++below.
		A [Context Provider]{.HTML-Keyboard} can delete a [Context Source
		Registration]{.HTML-Keyboard} from an NGSI-LD system as shown in Figure+++below.

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

		@@ -220,18 +222,18 @@ Figure: Delete context source registration use case

		#### 12.2.4.3 Input data

		Registration identifier (URI) of the [Context Source Registration]{.HTML-Keyboard} to be deleted
		(target registration).
		Registration identifier (URI) of the [Context Source
		Registration]{.HTML-Keyboard} to be deleted (target registration).

		#### 12.2.4.4 Behaviour

		- If the target [Context Source Registration]{.HTML-Keyboard} id is not present or it is not a
		valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be
		raised.
		- If the NGSI-LD endpoint does not know about the target context source
		registration, because there is no existing [Context Source Registration]{.HTML-Keyboard} whose
		id (URI) is equivalent, then an error of type [ResourceNotFound]{.HTML-Error}
		- If the target [Context Source Registration]{.HTML-Keyboard} id is not present
		or it is not a valid URI, then an error of type [BadRequestData]{.HTML-Error}
		shall be raised.
		- If the NGSI-LD endpoint does not know about the target context source
		registration, because there is no existing [Context Source
		Registration]{.HTML-Keyboard} whose id (URI) is equivalent, then an error of
		type [ResourceNotFound]{.HTML-Error} shall be raised.
		- Otherwise the [Context Source Registration]{.HTML-Keyboard} shall be removed.

		#### 12.2.4.5 Output data
		@@ -246,12 +248,14 @@ None.

		#### 12.3.2.1 Description

		This operation allows retrieving a specific [Context Source Registration]{.HTML-Keyboard} from an
		NGSI-LD system.
		This operation allows retrieving a specific [Context Source
		Registration]{.HTML-Keyboard} from an NGSI-LD system.

		#### 12.3.2.2 Use case diagram

		A [Context Consumer]{.HTML-Keyboard} or a [Context Provider]{.HTML-Keyboard} can retrieve a specific [Context Source Registration]{.HTML-Keyboard} from an NGSI-LD system as shown in Figure+++below.
		A [Context Consumer]{.HTML-Keyboard} or a [Context Provider]{.HTML-Keyboard} can
		retrieve a specific [Context Source Registration]{.HTML-Keyboard} from an
		NGSI-LD system as shown in Figure+++below.

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

		@@ -267,18 +271,18 @@ Figure: Retrieve context source registration use case

		#### 12.3.2.3 Input data

		[Context Source Registration]{.HTML-Keyboard} identifier (id) of the context source registration
		to be retrieved (target registration).
		[Context Source Registration]{.HTML-Keyboard} identifier (id) of the context
		source registration to be retrieved (target registration).

		#### 12.3.2.4 Behaviour

		- If the [Context Source Registration]{.HTML-Keyboard} id (_`id`_) is not present or it is not a
		valid URI, then an error of type [BadRequestData]{.HTML-Error} shall be
		raised.
		- If the NGSI-LD endpoint does not know about the target [Context Source Registration]{.HTML-Keyboard},
		because there is no existing [Context Source Registration]{.HTML-Keyboard} whose
		id (URI) is equivalent, then an error of type [ResourceNotFound]{.HTML-Error}
		shall be raised.
		- If the [Context Source Registration]{.HTML-Keyboard} id (_`id`_) is not
		present or it is not a valid URI, then an error of type
		[BadRequestData]{.HTML-Error} shall be raised.
		- If the NGSI-LD endpoint does not know about the target [Context Source
		Registration]{.HTML-Keyboard}, because there is no existing [Context Source
		Registration]{.HTML-Keyboard} whose id (URI) is equivalent, then an error of
		type [ResourceNotFound]{.HTML-Error} shall be raised.
		- Term to URI expansion of Attribute names shall be observed as mandated by
		Clause+++clause-8.2.4.
		- Otherwise return a JSON-LD object representing the [Context Source
		@@ -286,18 +290,18 @@ to be retrieved (target registration).

		#### 12.3.2.5 Output data

		A JSON-LD object representing the target [Context Source Registration]{.HTML-Keyboard} as mandated
		by Clause+++clause-5+++5.2.6.5.3.
		A JSON-LD object representing the target [Context Source
		Registration]{.HTML-Keyboard} as mandated by Clause+++clause-5+++5.2.6.5.3.

		### 12.3.3 Query Context Source Registrations

		#### 12.3.3.1 Description

		This operation allows discovering [Context Source Registrations]{.HTML-Keyboard} from an NGSI-LD
		system. The behaviour of the discovery of context source registrations differs
		significantly from the querying of entities as described in
		Clause+++clause-10+++10.4.3. The approach is that the client submits a query for
		entities as described in clause 5.7.2, but instead of receiving the Entity
		This operation allows discovering [Context Source Registrations]{.HTML-Keyboard}
		from an NGSI-LD system. The behaviour of the discovery of context source
		registrations differs significantly from the querying of entities as described
		in Clause+++clause-10+++10.4.3. The approach is that the client submits a query
		for entities as described in clause 5.7.2, but instead of receiving the Entity
		information, it receives a list of [Context Source
		Registrations]{.HTML-Keyboard} describing [Context Sources]{.HTML-Keyboard} that
		possibly have some of the requested Entity information. This means that the
		@@ -313,9 +317,9 @@ _`managementInterval`_, are considered.

		#### 12.3.3.2 Use case diagram

		A _Context Consumer_ can discover [Context Source Registrations]{.HTML-Keyboard} that may be able
		to provide (part of) the context information specified in the query from an
		NGSI-LD system as shown in Figure+++below.
		A _Context Consumer_ can discover [Context Source Registrations]{.HTML-Keyboard}
		that may be able to provide (part of) the context information specified in the
		query from an NGSI-LD system as shown in Figure+++below.

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

		@@ -359,24 +363,25 @@ Figure: Discover context source registrations use case
		retrieved. See Clause+++clause-7+++7.4.2.
		- A specified language filter as per Clause+++clause-7+++7.2.7 (optional).

		It is not possible to retrieve a set of [Context Source Registrations]{.HTML-Keyboard} related to
		entities by only specifying desired Entity identifiers, without further
		specifying restrictions on the entities' types or attributes, either explicitly,
		via lists of Entity types or of Attribute names, or implicitly, within an
		NGSI-LD query or geoquery.
		It is not possible to retrieve a set of [Context Source
		Registrations]{.HTML-Keyboard} related to entities by only specifying desired
		Entity identifiers, without further specifying restrictions on the entities'
		types or attributes, either explicitly, via lists of Entity types or of
		Attribute names, or implicitly, within an NGSI-LD query or geoquery.

		#### 12.3.3.4 Behaviour

		- Execute the behaviour defined in Clause+++clause-8+++8.2.3 on JSON-LD
		validation.
		- At least one of the following input data shall be provided:

		- a. selector of Entity Types;
		- b. list of Attribute names;
		- c. NGSI-LD Query;
		- d. NGSI-LD GeoQuery.

		- If none of them is provided, then an error of
		type [BadRequestData]{.HTML-Error}_list of Attribute names_
		- If none of them is provided, then an error of type
		[BadRequestData]{.HTML-Error} with a _list of Attribute names_

		- If the list of Entity identifiers includes a URI which it is not valid, or the
		query, geoquery or temporal query are not syntactically valid (as per

md/clause-14.md

+108 −93

File changed.

Preview size limit exceeded, changes collapsed.

md/clause-3_Definitions.md

+3 −3

Original line number	Diff line number	Diff line
		@@ -199,8 +199,8 @@ Brokers]{.HTML-Keyboard} and across domains
		NGSI-LD GeoProperty: subclass of NGSI-LD Property which is a description
		instance which associates a main characteristic, i.e. an NGSI-LD Value, to
		either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property,
		that uses the special _`hasValue`_ property to define its target value and
		holds a geographic location in GeoJSON format
		that uses the special _`hasValue`_ property to define its target value and holds
		a geographic location in GeoJSON format

		NGSI-LD Internal Linked Entity: [Linked Entity]{.HTML-Keyboard} that exists
		within the current NGSI-LD system