6 API HTTP Binding

6.1 Introduction

This clause defines the resources and operations of the NGSI-LD API. The NGSI-LD API is structured in terms of HTTP [3], [4] verbs, request and response payload bodies.

A non-normative OAS specification [i.12] of the referred HTTP binding can be found at [i.14].

6.2 Global Definitions and Resource Structure

All resource URIs of this API shall have the following root:

{apiRoot}/{apiName}/{apiVersion}/

NOTE 1:

The apiRoot discovery process is out of the scope of the present document.

NOTE 2:

The apiRoot for Context Source related aspects and the apiRoot for general Entity-related aspects can be different, e.g. the Context Source related aspects can be implemented by a Context Registry as shown for the distributed and federated architectures (see clause 4.3 ), whereas the Entity-related aspects would be implemented by a Context Broker .

NOTE 3:

The apiRoot for Context Source related aspects and the apiRoot for general Entity-related aspects can be different than the apiRoot for temporal aspects, e.g. the temporal aspects can be implemented by an NGSI-LD subsystem specialized in historical data.

The apiRoot includes the scheme ("http" or "https"), host and optional port, and an optional prefix string. The API shall support HTTP over TLS (also known as HTTPS - see IETF RFC 2818 [18]). TLS version 1.2 as defined by IETF RFC 5246 [19] shall be supported. HTTP without TLS is not recommended.

The apiName shall be set to "ngsi-ld" and the apiVersion shall be set to "v1" for the present document.

All resource URIs are defined relative to the above root URI. The structure of the resources under the root URI is shown in Figure 6.2‑1 and methods defined on them are shown in Table 6.2‑1.

Figure 6.2-1: Resource URI structure of the NGSI-LD API

Table 6.2-1: Resources and HTTP methods defined on them

Resource Name	Resource URI	HTTP Method	Meaning	Clauses
Entity List	/entities/	POST	Entity creation	5.6.1; 6.4.3.1
		GET	Query entities	5.7.2; 6.4.3.2
		DELETE	Purge entities	5.6.21; 6.4.3.3
Entity by id	/entities/{entityId}	GET	Entity retrieval by id	5.7.1; 6.5.3.1
		DELETE	Entity deletion by id	5.6.6; 6.5.3.2
		PATCH	Entity merge by id	5.6.17; 6.5.3.4
		PUT	Entity replacement by id	5.6.18; 6.5.3.3
Attribute List	/entities/{entityId}/attrs/	POST	Append Attributes to Entity	5.6.3; 6.6.3.1
Attribute List	/entities/{entityId}/attrs/	PATCH	Update Attributes of an Entity	5.6.2; 6.6.3.2
Attribute by id	/entities/{entityId}/attrs/{attrId}	PATCH	Partial Attribute update	5.6.4; 6.7.3.1
		DELETE	Attribute deletion	5.6.5; 6.7.3.2
		PUT	Attribute replacement	5.6.19; 6.7.3.3
Subscriptions List	/subscriptions/	POST	Create Subscription	5.8.1; 6.10.3.1
Subscriptions List	/subscriptions/	GET	Retrieve list of Subscriptions	5.8.4; 6.10.3.2
Subscription by Id	/subscriptions/{subscriptionId}	GET	Subscription retrieval by id	5.8.3; 6.11.3.1
		PATCH	Subscription update by id	5.8.2; 6.11.3.2
		DELETE	Subscription deletion by id	5.8.5; 6.11.3.3
Entity Types	/types/	GET	Retrieve available entity types	5.7.5 and 5.7.6; 6.25.3.1
Entity Type	/types/{type}	GET	Details about available entity type	5.7.7; 6.26.3.1
Attributes	/attributes/	GET	Available attributes	5.7.8 and 5.7.9; 6.27.3.1
Attribute	/attributes/{attrId}	GET	Details about available attribute	5.7.10; 6.28.3.1
Context source registration list	/csourceRegistrations/	POST	Csource registration creation	5.9.2; 6.8.3.1
Context source registration list	/csourceRegistrations/	GET	Discover Csource registrations	5.10.2; 6.8.3.2
Context source registration by Id	/csourceRegistrations/{registrationId}	GET	Csource registration retrieval by id	5.10.1; 6.9.3.1
		PATCH	Csource registration update by id	5.9.3; 6.9.3.2
		DELETE	Csource registration deletion by id	5.9.4; 6.9.3.3
Context source registration subscription list	/csourceSubscriptions/	POST	Create subscription to Csource registration	5.11.2; 6.12.3.1
Context source registration subscription list	/csourceSubscriptions/	GET	Retrieval of list of subscription to Csource registration	5.11.5; 6.12.3.2
Context source registration subscription by Id	/csourceSubscriptions/{subscriptionId}	GET	Csource registration subscription retrieval by id	5.11.4; 6.13.3.1
		PATCH	Csource registration subscription update by id	5.11.3; 6.13.3.2
		DELETE	Csource registration subscription deletion by id	5.11.6; 6.13.3.3
Entity Operations. Create	/entityOperations/create	POST	Batch Entity creation	5.6.7; 6.14.3.1
Entity Operations. Upsert	/entityOperations/upsert	POST	Batch Entity creation or update (upsert)	5.6.8; 6.15.3.1
Entity Operations. Update	/entityOperations/update	POST	Batch Entity update	5.6.9; 6.16.3.1
Entity Operations. Delete	/entityOperations/delete	POST	Batch Entity deletion	5.6.10; 6.17.3.1
Entity Operations. Query	/entityOperations/query	POST	Query entities based on POST	5.7.2; 6.23.3.1
Entity Operations. Merge	/entityOperations/merge	POST	Batch Entity merge	5.6.20; 6.31.3.1
Temporal Evolution of Entities	/temporal/entities/	POST	Temporal Evolution of an Entity creation	5.6.11; 6.18.3.1
Temporal Evolution of Entities	/temporal/entities/	GET	Query Temporal Evolution of Entities	5.7.4; 6.18.3.2
Temporal Evolution of an Entity by id	/temporal/entities/{entityId}	GET	Temporal Evolution of an Entity retrieval by id	5.7.3; 6.19.3.1
Temporal Evolution of an Entity by id	/temporal/entities/{entityId}	DELETE	Temporal Evolution of an Entity deletion by id	5.6.16; 6.18.3.2
Temporal Representation of Attribute List	/temporal/entities/{entityId}/attrs/	POST	Temporal Evolution of Attribute of an Entity instance addition	5.6.12; 6.20.3.1
Temporal Representation of Attribute by id	/temporal/entities/{entityId}/attrs/{attrId}	DELETE	Attribute from Temporal Evolution of an Entity deletion	5.6.13; 6.21.3.1
Temporal Representation of Attribute Instance by id	/temporal/entities/{entityId}/attrs/{attrId} /{instanceId}	PATCH	Attribute Instance from Temporal Evolution of an Entity update by instance id	5.6.14; 6.22.3.1
Temporal Representation of Attribute Instance by id	/temporal/entities/{entityId}/attrs/{attrId} /{instanceId}	DELETE	Attribute Instance from Temporal Evolution of an Entity deletion by instance id	5.6.15; 6.22.3.2
Create EntityMap for Query Temporal Evolution of Entities	/temporal/entityMaps/	GET	Query temporal evolution of entities for creating entity map	5.15.4; 6.35.3.1
Create EntityMap for Query Temporal Evolution of Entities	/temporal/entityMaps/	POST	Query temporal evolution of entities for creating entity map based on POST	5.15.4; 6.35.3.2
Temporal Query Operation	/temporal/entityOperations/query	POST	Query Temporal Evolution of Entities based on POST	5.7.4; 6.24.3.1
Add and List @context	/jsonldContexts	POST	Add a user @context to the internal cache	5.13.2; 6.29.3.1
Add and List @context	/jsonldContexts	GET	List all cached @contexts	5.13.3; 6.29.3.2
Serve, Delete and Reload @context	/jsonldContexts/{contextId}	GET	Serve one specific user @context	5.13.4; 6.30.3.1
Serve, Delete and Reload @context	/jsonldContexts/{contextId}	DELETE	Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it	5.13.5; 6.30.3.2
Create EntityMap for Query Entities	/entityMaps/	GET	Query entities for creating entity map	5.14.4; 6.34.3.1
Create EntityMap for Query Entities	/entityMaps/	POST	Query entities for creating entity map based on POST	5.14.4; 6.34.3.2
Retrieve, Update and Delete Entity Maps	/entityMaps/{entityMapId}	GET	EntityMap Retrieval by id	5.14.1; 6.32.3.1
		PATCH	EntityMap Update by id	5.14.2; 6.32.3.2
		DELETE	EntityMap Deletion by id	5.14.3; 6.32.3.3
Retrieve Context Source Identity Information	/info/sourceIdentity	GET	Context Source Identity Retrieval	5.15.1; 6.33.3.1

6.3 Common Behaviours

6.3.1 Introduction

This clause extends the API common behaviours to the particularities of the HTTP REST binding. For each operation implementations shall exhibit the common behaviours as specified by clause 5.5 and the behaviours defined by the present clause.

6.3.2 Error Types

This clause associates API error types (which shall be contained in the response payload body) defined by clause 5.5.2 with HTTP status codes as shown in Table 6.3.2‑1.

Table 6.3.2-1: Mapping of error types to HTTP status codes

Error Type	HTTP status
https://uri.etsi.org/ngsi-ld/errors/InvalidRequest	400
https://uri.etsi.org/ngsi-ld/errors/BadRequestData	400
https://uri.etsi.org/ngsi-ld/errors/AlreadyExists	409
https://uri.etsi.org/ngsi-ld/errors/OperationNotSupported	422
https://uri.etsi.org/ngsi-ld/errors/ResourceNotFound	404
https://uri.etsi.org/ngsi-ld/errors/InternalError	500
https://uri.etsi.org/ngsi-ld/errors/TooComplexQuery	403
https://uri.etsi.org/ngsi-ld/errors/TooManyResults	403
https://uri.etsi.org/ngsi-ld/errors/LdContextNotAvailable	504
https://uri.etsi.org/ngsi-ld/errors/NoMultiTenantSupport	501
https://uri.etsi.org/ngsi-ld/errors/NonexistentTenant	404

In addition, implementations shall support the standard specific errors of HTTP bindings, such as the following:

"Method Not Allowed" (405) which shall be raised when a client invokes a wrong HTTP verb over a resource. Implementations shall provide the allowed HTTP methods as mandated by IETF RFC 7231 [3] in section 6.5.5.
"Request Entity too large" (413) which shall be raised when the HTTP input data stream provided by a client was too large i.e. too many bytes.
"Length required" (411) which shall be raised when an HTTP request provided by a client does not define the "Content-Length" HTTP header.
"Unsupported Media Type" (415) which shall be raised when an HTTP request payload body (as per the "Content-Type" header) it is not "application/json" nor "application/ld+json".
"Not Acceptable" 406) which shall be raised when the response media types that are acceptable by a client (as per the "Accept" header) do not include or expand to "application/json" nor "application/ld+json".

6.3.3 Reporting errors

When an API operation results in an error, implementations shall return an HTTP response as follows:

Content-Type: application/json.
HTTP Status Code: As per clause 6.3.2 depending on error type.
Payload body: A JSON object including all the terms defined by clause 5.5.3.

6.3.4 HTTP request preconditions

For HTTP POST, PATCH and PUT HTTP requests implementations shall check the following preconditions:

Content-Type header shall be "application/json" or "application/ld+json".
Content-Length header shall include the length of the request payload body.

For HTTP PATCH requests "application/merge-patch+json" is allowed as Content-Type, as mandated by IETF RFC 7396 [16]. Implementations shall interpret such MIME type as equivalent to "application/json".

For HTTP GET requests and for HTTP POST operations corresponding to “Query Entities” (see clause 5.7.2) and “Query Temporal Evolutions of Entities” (see clause 5.7.4), implementations shall check the following preconditions:

Accept header shall include (or define a media range that can be expanded to) at least one of:

"application/json"
"application/ld+json"
"application/geo+json"

The order of the list above is significant. If the Accept header can be expanded to more than one of the options of the list, the first one of the list shall be selected, unless amended by the HTTP Accept header processing rules, e.g. the presence of a "q" parameter indicating a relative weight, (as mandated by IETF RFC 7231 [3], section 5.3.2) require otherwise.

If the Accept header is not present, "application/json" shall be assumed.

If an incoming HTTP request does not meet the preconditions stated above, an HTTP error response of type InvalidRequest shall be returned, with the following exceptions:

"Content-Length" HTTP header absence, shall result in just a 411 HTTP status code (without any payload body).
Unsupported Media Type, i.e. "Content-Type" header is not "application/json" nor "application/ld+json", shall result in just a 415 HTTP status code (without any payload body).
Not Acceptable Media Type, i.e. "Accept" header does not imply "application/json" nor "application/ld+json", shall result in a 406 HTTP status code and the body of the message shall contain the list of the available representations of the resources.

Notwithstanding the above, if the Accept Header is set to "application/geo+json":

For Context Information Consumption operations only, specifically "Retrieve Entity" (see clause 5.7.1) and "Query Entity" (clause 5.7.2) GeoJSON is considered as an acceptable content type and a GeoJSON payload will be returned.
For all other operations, the request will result in a Not Acceptable Media Type error, returning a 406 HTTP status code and the body of the message shall contain the list of the available representations of the resources.

6.3.5 JSON-LD @context resolution

In the HTTP REST binding, implementations shall resolve the JSON-LD @context associated to an incoming HTTP request as follows:

If the request verb is GET or DELETE, then the associated JSON-LD @context shall be obtained from a Link header [7] as mandated by JSON-LD [2], section 6.2. In the absence of such Link header, then the associated @context shall be the default JSON-LD @context.

EXAMPLE:

The structure of the referred Link header is shown below. The first component (between < > ) is a dereferenceable URI pointing to the JSON-LD document which contains the @context to be used to expand the terms used by the corresponding operation. The second parameter is a fixed, non-dereferenceable URI used to denote a unique identifier and semantics for this header (marking it as a link to a JSON-LD @context ). The third and final parameter flags the MIME type of the linked resource (JSON-LD).

If the request verb is POST, PATCH or PUT and the Content-Type header is "application/json", then the @context shall be obtained from a Link Header as mandated by JSON-LD [2], section 6.2. In the absence of such Link Header, then the @context shall be the default @context. In any case, if the request payload body (as JSON) contains a @context term, then an HTTP error response of type BadRequestData shall be raised.
If the request verb is POST, PATCH or PUT and the Content-Type header is "application/ld+json", then the associated @context shall be obtained from the request payload body itself. If no @context can be obtained from the request payload body, then an HTTP error response of type BadRequestData shall be raised. In any case, the presence of a JSON-LD Link header in the incoming HTTP request when the Content-Type header is "application/ld+json" shall result in an HTTP error response of type BadRequestData.

In summary, from a developer's perspective, for POST, PATCH and PUT operations, if MIME type is "application/ld+json", then the associated @context shall be provided only as part of the request payload body. Likewise, if MIME type is "application/json", then the associated @context shall be provided only by using the JSON-LD Link header. No mixes are allowed, i.e. mixing options shall result in HTTP response errors. Implementations should provide descriptive error messages when these situations arise.

In contrast, GET and DELETE operations always take their input @context from the JSON-LD Link Header.

6.3.6 HTTP response common requirements

Implementations shall honour the Accept header provided by HTTP requests as mandated by clause 6.3.4:

If the target response's MIME type is "application/json" such response shall include a Link to the associated JSON-LD @context as mandated by [2], section 6.2.

If the Prefer header [26] is set to "ngsi-ld=<version>" then implementations shall set the Preference-Applied header to "ngsi-ld=<conformant-version>" in the returned response indicating which version of the NGSI-LD specification the payload body conforms to, as mandated in clause 4.3.6.8.

If the target response's MIME type is "application/ld+json", then the response payload body provided by the HTTP response shall include a JSON-LD @context.

If the Prefer Header [26] is set to "ngsi-ld=<version>" then implementations shall set Preference-Applied header to "ngsi-ld=<conformant-version>" in the returned response indicating which version of the NGSI-LD specification the payload body conforms to, as mandated in clause 4.3.6.8.

If the target response's MIME type is "application/geo+json" and the Prefer Header [26] is omitted or set to "body=ld+json", then the response payload body provided by the HTTP response shall include a JSON-LD @context, and the representation of the entities shall be in GeoJSON format in the response payload body.
If the target response's MIME type is "application/geo+json" and the Prefer Header [26] is set to "body=json" such response shall include a Link to the associated JSON-LD @context as mandated by [2], section 6.2 and the representation of the entities shall be in GeoJSON format in the response payload body, and @context shall be omitted from the payload body.

Operations where the response payload body is not present such as successful HTTP POST, PATCH, PUT or DELETE operations and all error responses, do not include the Link header in the response.

Operations that result in an error that return a payload or that result in a partial success (207 Multi-Status) shall always respond with MIME type "application/json", regardless of the Accept header. It is assumed that if a client application understands any of the supported MIME types, the application shall understand "application/json" errors. Only Fully Qualified Names shall be used in the payload body of error or partial success responses, as there is no context present.

No Content-Length HTTP header shall be present if the response code is 204.

6.3.7 Representation of Entities

For HTTP GET and POST operations corresponding to “Retrieve Entity” (see clause 5.7.1) and “Query Entities” (see clause 5.7.2), Context Broker implementations shall support the parameter specified in Table 6.3.7‑1, which specifies all possible supported representations formats.

In contrast, at a minimum, registered Context Source implementations shall support the normalized representation of Entities as default. When a registered Context Source is unable to support additional representations, a 501 Not Implemented Error shall be raised.

Table 6.3.7-1: Entity representations: format + options parameter

Name	Data Type	Cardinality	Remarks
format	String	0..1	When its value is "normalized", a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2, 4.5.18.2 and 4.5.20.2. When its value is "concise", a concise lossless representation of Entities shall be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as defined in clauses 4.5.2.3, 4.5.3.3, 4.5.18.3 and 4.5.20.3. In this case the Context Broker will return data in the most concise lossless representation possible, for example removing all Attribute type members. When its value is "simplified" (or its synonym "keyValues"). a simplified representation of Entities shall be provided as defined by clause 4.5.4 If the Accept Header is set to "application/geo+json" the response will be in simplified GeoJSON format as defined by clause 4.5.17.
options	Comma separated list of strings	0..1	An alternative mechanism to include the format parameter. Deprecated When its value includes the keyword "normalized", a normalized representation of Entities shall be provided as defined by clause 4.5.1, with Attributes returned in the normalized representation as defined in clauses 4.5.2.2, 4.5.3.2, 4.5.18.2 and 4.5.20.2. When its value includes the keyword "concise", a concise lossless representation of Entities shall be provided as defined by clause 4.5.1. with Attributes returned in the concise representation as defined in clauses 4.5.2.3, 4.5.3.3, 4.5.18.3 and 4.5.20.3. In this case the Context Broker will return data in the most concise lossless representation possible, for example removing all Attribute type members. When its value includes the keyword "simplified" (or its synonym "keyValues"). a simplified representation of Entities shall be provided as defined by clause 4.5.4. If the Accept Header is set to "application/geo+json" the response will be in simplified GeoJSON format as defined by clause 4.5.17.

6.3.8 Notification behaviour

In the HTTP binding a notification that is triggered by a subscription shall be sent by issuing an HTTP POST request targeted to the value of notification.endpoint.uri member of the subscription structure (defined by clauses 5.2.12, 5.2.14 and 5.2.15). For the HTTP binding, the protocol part of the endpoint URI is http or https. In case the optional MQTT notification binding (clause 7) is supported, the protocol part of the endpoint URI can also be mqtt or mqtts. The MIME type associated to the POST request shall be "application/json" by default. However, this can be changed to "application/ld+json", or "application/geo+json" by means of the endpoint.accept member.

If the target MIME type is "application/json" then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new custom HTTP header for each member named "key" of the key, value pairs that make up the array shall be generated and included in the HTTP POST's list of headers. The content of each custom header shall be set equal to the content of the corresponding "value" member of the KeyValuePair. "Key" and "value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

If the target MIME type is "application/geo+json" and the notification.endpoint.receiverInfo member contains a key "Prefer" whose value is set to "body=json" then the HTTP notification request shall include a Link header with a reference to the corresponding JSON-LD @context as mandated by the JSON-LD specification [2], section 6.2 (to the default JSON-LD @context if none available).

If the target MIME type is "application/geo+json" and the notification.endpoint.receiverInfo contains a key "Prefer" whose value is set to "body=ld+json" or the "Prefer" key is omitted or notification.endpoint.receiverInfo does not exist, then the HTTP notification request includes an @context element in the payload body.

6.3.9 Csource Notification behaviour

In the HTTP binding a csource notification that is triggered by a csource subscription shall be sent by issuing an HTTP POST request targeted to the value of notification.endpoint.uri member of the csource subscription structure (defined by clauses 5.2.12 and 5.2.14). The MIME type associated to the POST request shall be "application/json" by default. However, this can be changed to "application/ld+json" by means of the endpoint.accept member.

If the optional array (of KeyValuePair type, as defined by clause 5.2.22) notification.endpoint.receiverInfo of the subscription is present, then a new custom HTTP Header for each member named "key" of the key, value pairs that make up the array shall be generated and included in the HTTP POST's list of headers. The content of each custom header shall be set equal the content of the corresponding "value" member of the KeyValuePair. "Key" and "value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

6.3.10 Pagination behaviour

For HTTP operations corresponding to the operations listed in clause 4.12 (see Table 6.2‑1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.3.10‑1.

Table 6.3.10-1: Pagination: limit parameter

Name	Data Type	Cardinality	Remarks
limit	Integer	0..1	Only values greater or equal to 0. It defines the limit to the number of NGSI-LD Elements that shall be retrieved at a maximum as mandated by clause 5.5.9. The value 0 is only allowed in combination with the count URI parameter.

This clause defines the specific HTTP binding mechanisms that shall be used in conjunction with the behaviours defined by clause 5.5.9. Particularly, to flag the existence of related pages that could be retrieved when dealing with query operations involving pagination, NGSI-LD Systems implementing the HTTP binding shall use the HTTP Link header field as mandated by IETF RFC 8288 [7], clause 3, as follows:

The pointers to the next and previous pages (when needed as mandated by clause 5.5.9) shall be serialized as link-value elements. The content of such link-value(s) shall be:

For the next page, the Link Target shall be a URI-reference that could be dereferenced by an NGSI-LD Client to retrieve the next page of NGSI-LD Elements. In addition, the Link Relation Type shall be equal to "next", registered under the IANA Registry of Link Relation Types [20].
For the previous page, the Link Target shall be a URI-reference that could be dereferenced by an NGSI-LD Client to retrieve the previous page of NGSI-LD Elements. In addition, the Link Relation Type shall be equal to "prev", registered under the IANA Registry of Link Relation Types [20].

At least, the "type" Link Target Attribute shall be included by the previously described serialized Link Header, as mandated by IETF RFC 8288 [7], , and its value shall be exactly equal to the media type resulting from the original request made by the NGSI-LD Client (the request that triggered the current pagination iteration).

EXAMPLE:

If the media type requested originally was "application/json" then during the entire pagination iteration the value of the Link Target Attribute "type" shall be "application/json".

If the transparent pagination option as described in is used, the URI-references for the "next" and "prev" link to the next and previous pages respectively should include the limit parameter as specified in Table 6.3.10‑1 and the offset parameter as specified in Table 6.3.10‑2, giving the Context Consumer more control, i.e. to adapt the size of the page using limit and jump to a desired set of elements in the results using offset.

Table 6.3.10‑2: Pagination: offset parameter

Name	Data Type	Cardinality	Remarks
offset	Integer	0..1	Only values greater or equal to 0. It defines the offset of the first NGSI-LD Element that shall be retrieved from the beginning of the result set. If offset is set to a value larger than the result set, the offset should be assumed to be equal to the size of the result set, i.e. only the last element of the result set is to be returned if there are any results.

offset

Integer

0..1

Only values greater or equal to 0.

It defines the offset of the first NGSI-LD Element that shall be retrieved from the beginning of the result set. If offset is set to a value larger than the result set, the offset should be assumed to be equal to the size of the result set, i.e. only the last element of the result set is to be returned if there are any results.

Temporal representation of resources adds an additional dimension to the pagination. Depending on the requested time range, the response will contain multiple instances of the requested Attribute, and therefore an additional pagination mechanism for those temporal representations is required, in order to limit the time range of the response. If no limits are specified, a default limit is enforced, depending on implementation specific configurations. For HTTP operations on Temporal Evolutionof Entities, implementations shall use the Partial Content Response (206) as specified by IETF RFC 7233 [31], clause 4.1, if the implementation is not able to respond with the full representation at once. In this case, for requests where the parameter lastN is present, pagination shall happen "backwards" (from the most recent to the least recent timestamp in the requested time range). For requests without the parameter lastN, pagination shall happen "forwards" (from the least recent to the most recent timestamp in the requested time range).

This is achieved by including the "Content-Range" header field with the following contents:

"unit" shall be equal to "DateTime";
"range-start" and "range-end" shall be of type DateTime. They depend on the requested time relationship timerel (as defined by clause 4.11), as follows:

If the lastN parameter is present, pagination shall happen "backwards":

"range-start" shall be equal to "timeAt" for requests with timerel=before, "endTimeAt" for requests with timerel=between, or the most recent timestamp in the range of the response, for requests with timerel=after;
"range-end" shall be equal to the least recent timestamp in the range of the response;
"size" shall be equal to the requested lastN.

If the lastN parameter is not present, pagination shall happen "forwards":

"range-start" shall be equal to timeAt for requests with timerel=after or timerel=between, or the least recent timestamp in the range of the response, for requests with timerel=before;
"range-end" shall be equal to the most recent timestamp in the range of the response;
"size" shall be equal to "*".

6.3.11 Including system Attributes

For HTTP GET operations performed over the resources /entities/, /subscriptions/, /csourceRegistrations/, /csourceSubscriptions/, /temporal/entities/ and all of its sub-resources, and for HTTP POST operations corresponding to “Query Entities” (see clause 5.7.2) and “Query Temporal Evolutions of Entities” (see clause 5.7.4), implementations shall support the parameter specified in Table 6.3.11‑1. Implementations shall not raise an error if they do not hold system generated temporal attributes.

Table 6.3.11-1: Including system generated temporal attributes: options parameter

Name	Data Type	Cardinality	Remarks
options	Comma separated list of strings	0..1	When its value includes the keyword "sysAttrs", a representation of NGSI-LD Elements shall be provided so that the system generated temporal attributes createdAt, modifiedAt and the system temporal attribute expiresAt are included in the response payload body where known. In the case of temporal representations, also the system generated temporal attribute deletedAt is included, if the NGSI-LD Element has been deleted.

6.3.12 Simplified or aggregated temporal representation of Entities

For HTTP GET and POST operations corresponding to “Retrieve Temporal Evolution of an Entity” (see clause 5.7.3) and “Query Temporal Evolution of Entities” (see clause 5.7.4), implementations shall support the parameter specified in Table 6.3.12‑1.

Table 6.3.12-1: Temporal Entity representations: format + options parameters

Name	Data Type	Cardinality	Remarks
format	String	0..1	It shall be one of: "temporalValues", "aggregatedValues". When its value is "temporalValues", a simplified temporal representation of entities shall be provided as defined by clause 4.5.8. When its value is "aggregatedValues", an aggregated temporal representation of entities shall be provided as defined by clause 4.5.19.
options	Comma separated list of strings	0..1	An alternative mechanism to include the format parameter. Deprecated When its value includes the keyword "temporalValues", a simplified temporal representation of entities shall be provided as defined by clause 4.5.8. When its value includes the keyword "aggregatedValues", an aggregated temporal representation of entities shall be provided as defined by clause 4.5.19. Only one of the two keywords can be present in the values of the parameter. If both format and options are present, the value of the format parameter shall take precedence.

6.3.13 Counting number of results

This clause implements the behaviour described in clause 4.13, in case of HTTP binding.

Table 6.3.13-1: Counting number of results: count parameter

Name	Data Type	Cardinality	Remarks
count	Boolean	0..1	If true, then a special HTTP header (NGSILD-Results-Count) is set in the response. Regardless of how many entities are actually returned (maybe due to the limit URI parameter), the total number of matching results (e.g. number of Entities) is returned.

This clause defines the specific HTTP binding mechanisms that can be useful to plan the limit and offset URI parameters for pagination, thus allowing to convey an overview of the number of entities in a system.

To get only the count itself, and no entities, the URI parameter limit may have the value "0", and an empty array shall be returned as payload body.

Setting the URI parameter limit to zero without including the count URI parameter will result in a 400 BadRequest error.

6.3.14 Tenant specification

If the system implementing the NGSI-LD API supports multi-tenancy as described in clause 4.14 and clause 5.5.10, the Tenant, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header "NGSILD-Tenant", whose value is the String identifying the Tenant. In case the target Tenant is the default Tenant, the HTTP header is omitted. If the HTTP header "NGSILD-Tenant" is present in the HTTP request, it shall also be present in HTTP response. This also applies to HTTP notifications sent as a result of subscriptions with an "NGSILD-Tenant" HTTP header (clause 6.3.8).

6.3.15 GeoJSON representation of spatially bound entities

For HTTP GET and POST operations corresponding to “Retrieve Entity” (see clause 5.7.1) and “Query Entities” (see clause 5.7.2), if the GeoJSON Accept header ("application/geo+json") is present, implementations shall render the entities of the response in the GeoJSON format, as described in clause 5.2.29.

For GeoJSON representations, a GeoProperty may be selected as the geolocation to be used as the geometry within the GeoJSON payload. If no geometryProperty parameter is specified, then the location GeoProperty of the Entity is used.

Table 6.3.15-1: Selecting a geometry

Name	Data Type	Cardinality	Remarks
geometryProperty	String	0..1	If not present, "location" is used.
datasetId	String	0..1	Shall be valid URI. If the referenced GeoProperty consists of an attribute with multiple instances the datasetId specifies which instance of the value is to be selected. If not present, the default instance is used.

6.3.16 Expiration time for cached @contexts

Implementations shall comply with the Expires header field (section 5.3 of IETF RFC 7234 [30]) or a max-age or s-maxage response directive of Cache-Control header field (section 5.2.2 of IETF RFC 7234 [30]) that may be present in the downloaded @context. This means that implementations shall periodically invalidate the "Cached" @contexts according to the headers mentioned above. Since origin servers do not always provide explicit expiration times, implementations should assign a heuristic (for instance according to IETF RFC 7234 [30] section 4.2.2) expiration time when an explicit time is not specified.

6.3.17 Distributed Operations Caching and Timeout Behaviour

The caching of response data received from forwarded HTTP GET requests is optionally supported by Context Brokers. For HTTP GET operations performed over the resources /entities and /entities/{entity-id}, where a Context Source Registration matches the request and a previous forwarded response has been cached and a subsequent request occurs before the Context Source Registration cacheDuration (as defined in Table 5.2.34‑1) has been reached, the result may incorporate data cached from a previous response. To indicate that data from a cache has been included in the response, the HTTP header "NGSILD-Warning" shall be included. The value shall match the IANA Warning Code [32] 110 - Response is Stale.

"NGSILD-Warning" HTTP headers shall also be used to indicate instances of abnormal behaviour for distributed HTTP GET operations performed over the resources /entities and /entities/{entity-id}.

Table 6.3.17-1: NGSI-LD Warning Codes

IANA Warning Code	Remarks
110 - Response is Stale	No request was made to a specified registration endpoint - data from a cached value has been reused and it has been incorporated into the response.
111 - Revalidation Failed	Although data was received from the registration endpoint within the specified timeout period, the payload of the response was invalid. This could occur if the payload was corrupted or a non-NGSI payload was received.
199 - Miscellaneous Warning	No response was received from the registration endpoint within the specified timeout period or a registration loop has been detected.
299 - Miscellaneous Persistent Warning	An error response (such as 403 - Forbidden) was received from the registration endpoint within the specified timeout period. This could occur if the Context Broker has insufficient access rights to retrieve the data.

For distributed HTTP GET operations, registered context sources should always respond with a valid NGSI-LD payload. The Context Broker shall successfully parse this data and invalid non-NGSI-LD payloads shall be rejected and not incorporated into the overall response. It should be noted that a registration endpoint responding with no data and the HTTP status code 404 - Not Found should not be considered as abnormal behaviour for distributed operations.

For all other operations, which correspond to HTTP Unsafe methods, the error response should be as informative as possible.

In the case of an exclusive or redirect registration, where all of the data is held outside of the Context Broker and held in a single registered source, the following errors shall be returned:

508 Loop Detected – if the single registered source and tenant is registered to redirect back on to the Context Broker.
504 Gateway Timeout - if the single registered source fails to respond in time.
404 Not Found - if resources not found within the single registered source.
502 Bad Gateway - if the single forwarded request fails for any other reason such as the Context Broker itself having insufficient access rights.

In the case of an inclusive or redirect registration, where an entity is distributed over multiple equally valid endpoints, but when updating the state of the distributed entity, an error response is returned from one or more registered sources:

207 Multi Status.

In the case of an auxiliary registration HTTP unsafe methods are not supported.

Whenever failures or timeouts occur, Context Brokers may optionally decline to make subsequent requests to the same registration endpoint until the cooldown period (as defined in Table 5.2.9-1) has been reached.

6.3.18 Limiting Distributed Operations

The parameter described in this clause limits the execution of an operation to a local Context Source or Context Broker (clause 5.5.13). It amends the matching Context Source Registrations behaviour as described in , in the case of the HTTP binding in order to avoid cascading distributed operations (see clause 4.3.6.4). For all operations the resources /entities/, /types/, /attributes/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ (and their respective child resources) implementations shall support the HTTP query parameter specified in Table 6.3.18‑1. The Registry API operations are always local and thus are not included here.

Table 6.3.18-1: Limiting distributed operations: local parameter

Name	Data Type	Cardinality	Remarks
local	Boolean	0..1	If local=true then no Context Source Registrations shall be considered as matching to avoid cascading distributed operations (see clause 4.3.6.4)

Furthermore, to avoid infinite loops, for all operations, the resources /entities/, /types/, /attributes/, /subscriptions/, /csourceSubscriptions/, /entityOperations/, /temporal/entities/ and temporal/entityOperations/ implementations shall fully support the HTTP Via Header (IETF RFC 7230 [27]) as specified in Table 6.3.18‑2. AnyContext Broker implementation passing a distributed operation request onward to another Context Source shall send an additional field value on the Via header field using its own unique Context Source hostAlias (see clause 5.2.40) as the pseudonym.

Table 6.3.18-2: Request Headers

Name	Data Type	Cardinality	Remarks
Via	String as defined in IETF RFC 7230 [27]	0..1	If present, the listing of previously encountered Context Sources supplied is used when determining matching registrations

6.3.19 Extra information to provide when contacting Context Source

As specified in clauses 4.3.6.5 and 4.3.6.6, extra information to be provided when contacting a Context Source can be specified in the optional array (of KeyValuePair type, as defined by clause 5.2.22) contextSourceInfo of the CSourceRegistration.

In the HTTP binding, if the "jsonldContext" key is present, the URL value is placed in an HTTP Link Header as described by the JSON-LD specification [2], section 6.2 and, whenever a payload body is present in the request, the HTTP Content-Type Header is set to "application/json". For all other keys, a new custom HTTP header is added for each member named "key" of the key-value pairs that make up the array shall be generated and included in the HTTP list of headers. The content of each custom header shall be set equal to the content of the corresponding "value" member of the KeyValuePair, unless the special value "urn:ngsi-ld:request" has been set, in which case the value is to be taken from the triggering request, if present there. "Key" and "value" members shall adhere to IETF RFC 7230 [27] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

Headers derived from other elements of the CSourceRegistration, e.g. "NGSILD-Tenant", take precedence and cannot be overridden using contextSourceInfo. The same applies for headers generally set by HTTP itself, e.g. Content-length.

6.3.20 Invalid parameters

If an HTTP request for an operation contains parameters that are incompatible with the operation, or it contains values of the options parameter that are not supported by the operation, an HTTP error response of type InvalidRequest should be returned.

6.3.21 Optional profile information regarding versioning and datatype conformance

In the HTTP Binding, if an HTTP Link header with a profile parameter in accordance with IETF RFC 6906 [33], is found set to <https://uri.etsi.org/ngsi-ld/profile/version> then implementations that are only partially capable of interpreting the datatypes conformant to the supplied NGSI-LD version may use this information to allow the payload to be accepted within the constraints of the current implementation (see clause 5.5.4) through amending the payload body and applying the fallbacks defined within clause 4.3.6.8.

6.4 Resource: entities/

6.4.1 Description

This resource represents the entities known to an NGSI-LD system.

6.4.2 Resource definition

Resource URI:

/entities/

6.4.3 Resource methods

6.4.3.1 POST

This method is bound to the operation "Create Entity" and shall exhibit the behaviour defined by clause 5.6.1, taking the entity to be created from the HTTP request payload body. Figure 6.4.3.1‑1 shows the Create Entity interaction and Table 6.4.3.1‑1 describes the request body and possible responses.

Figure 6.4.3.1-1: Create Entity interaction

Table 6.4.3.1-1: Post Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity	1	Payload body in the request contains a JSON-LD object which represents the entity that is to be created.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	201 Created	The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created entity resource.
	BatchOperationResult	1	207 Multi-Status	The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created entity resource. If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail member should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	409 Conflict	It is used to indicate that the entity or an exclusive or redirect registration defining the entity already exists, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	422 Unprocessable Entity	It is used to indicate that the operation is not available, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.4.3.2 GET

This method is associated to the operation "Query Entities" and shall exhibit the behaviour defined by clause 5.7.2, providing entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Query Entities" operations via POST is defined in clause 6.23. Figure 6.4.3.2‑1 shows the query entities interaction.

Figure 6.4.3.2-1: Query Entities interaction

The query parameters that shall be supported by implementations are those defined in Table 6.4.3.2‑1, the request headers that shall be supported by implementations are those defined in Table 6.4.3.2‑2 and Table 6.4.3.2‑3 describes the request body and possible responses.

Table 6.4.3.2-1: Query parameters

Name	Data Type	Cardinality	Remarks
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
type	String	0..1 At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Selection of Entity Types as per clause 4.17. "" is also allowed as a value and local* is implicitly set to true and shall not be explicitly set tofalse.
idPattern	Regular expression as defined by [11]	0..1	Regular expression that shall be matched by entity ids.
attrs	Comma separated list of strings	0..1 At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	A synonym for a combination of the pick andq parameters. Deprecated Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entities and also included in the response, i.e. only Entities that contain at least one of the Attributes in attrs are to be included in the response, and only the Attributes listed in attrs are to be included in each of the Entities of the response.
pick	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name). When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.
omit	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name). When defined, the listed Entity members are removed from each Entity within the payload.
q	String	0..1 At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Query as per clause 4.9.
expandValues	Comma separated list of strings	0..1	Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied @context prior to executing a query. It is part of query.
jsonKeys	Comma separated list of strings	0..1	Each String is an Attribute (Property or Relationship) name. 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.
csf	String	0..1	Context Source filter as per clause 4.9.
geometry	String	0..1 It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or geometry shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Geometry as per clause 4.10. It is part of geoquery.
georel	String	0..1 It shall be 1 if geometry or coordinates are present.	Geo relationship as per clause 4.10. It is part of geoquery.
coordinates	String	0..1 It shall be one if geometry or georel are present.	Coordinates serialized as a string as per clause 4.10. It is part of geoquery.
geoproperty	String	0..1 It shall be ignored unless a geoquery is present.	It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. By default, will be location (see clause 4.7).
geometryProperty	String	0..1	It represents a Property name. In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language.
scopeQ	String	0..1	Scope query (see clause 4.19).
containedBy	Comma separated list of URIs	0..1	List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if joinLevel is present.
join	String	0..1	The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: "flat", "inline", "@none".
joinLevel	Positive Integer	0..1	Depth of Linked Entity retrieval to apply. Only applicable if join parameter is present.
datasetId	Comma separated list of strings	0..1	Shall be valid URIs, "@none" for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5.
entityMap	Boolean	0..1	If true, the location of the EntityMap used in the operation is returned in the response.
entityMapLifetime	String	0..1	Suggested duration, represented in ISO 8601 format [17], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration.Only applicable if entityMap is set to true.
splitEntities	Boolean	0..1	If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when 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. The parameter does not apply in case local is true. The default value should be decided by implementation; it should be configurable.

Table 6.4.3.2-2: Request Headers

Name	Data Type	Cardinality	Remarks
NGSILD-EntityMap	URI	0..1	If present, the EntityMap supplied is used for determining the set of Entities requested during the query operation. The location of the EntityMap used in the query operation is returned in the response.

Table 6.4.3.2-3: Get Entities request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Entity[]	1	200 OK 201 Created (in case an EntityMap has been (re)created)	A response body containing the query result as a list of entities, unless the Accept Header indicates that the Entities are to be rendered as GeoJSON. If an EntityMap has been requested, the HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource used in the operation.
	Entity[]	1	203 Non-Authoritative Information	As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	GeoJSON FeatureCollection	1	200 OK 201 Created (in case an EntityMap has been (re)created)	If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned. If an EntityMap has been requested, the HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource used in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	501 Not Implemented	It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7.

6.4.3.3 DELETE

This method is associated to the operation "Purge Entities" and shall exhibit the behaviour defined by clause 5.6.21, providing entities as part of the HTTP response payload body. Figure 6.4.3.3‑1 shows the query entities interaction.

Figure 6.4.3.3‑1: Purge Entities interaction

The query parameters that shall be supported by implementations are those defined in Table 6.4.3.3‑1, the request headers that shall be supported by implementations are those defined in Table 6.4.3.3‑2 and Table 6.4.3.3‑3 describes the request body and possible responses.

Table 6.4.3.3-1: Query parameters

Name	Data Type	Cardinality	Remarks
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
type	String	0..1 At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Selection of Entity Types as per clause 4.17. “” is also allowed as a value and local* is implicitly set to true and shall not be explicitly set to false.
idPattern	Regular expression as defined by [11]	0..1	Regular expression that shall be matched by entity ids.
drop	Comma separated list of strings	0..1	Each String is an Attribute name. When defined, every Entity within the payload body is reduced to not contain the listed Entity members.
keep	Comma separated list of strings	0..1	Each String is an Attribute name. When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.
q	String	0..1 At least one among: type, attrs, q, or georel shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Query as per clause 4.9.
csf	String	0..1	Context Source filter as per clause 4.9.
geometry	String	0..1 It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or geometry shall be present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Geometry as per clause 4.10. It is part of geoquery.
georel	String	0..1 It shall be 1 if geometry or coordinates are present.	Geo relationship as per clause 4.10. It is part of geoquery.
coordinates	String	0..1 It shall be one if geometry or georel are present.	Coordinates serialized as a string as per clause 4.10. It is part of geoquery.
geoproperty	String	0..1 It shall be ignored unless a geoquery is present.	It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery. By default, will be location (see clause 4.7).
geometryProperty	String	0..1	It represents a Property name. In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field.
scopeQ	String	0..1	Scope query (see clause 4.19).

Table 6.4.3.3-2: Request Headers

Name	Data Type	Cardinality	Remarks
NGSILD-EntityMap	URI	0..1	If present, the EntityMap supplied is used for determining the set of Entities requested during the purge operation. The location of the EntityMap used in the purge operation is returned in the response

Table 6.4.3.3-3: Purge Entities request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	BatchOperationResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.5 Resource: entities/{entityId}

6.5.1 Description

This resource represents an entity known to an NGSI-LD system.

6.5.2 Resource definition

Resource URI:

/entities/{entityId}

Resource URI variables for this resource are defined in Table 6.5.2‑1.

Table 6.5.2-1: URI variables

Name	Definition
entityId	Id (URI) of the entity to be retrieved

6.5.3 Resource methods

6.5.3.1 GET

This method is associated to the operation "Retrieve Entity" and shall exhibit the behaviour defined by clause 5.7.1. The Entity identifier is the value of the resource URI variable "entityId". Figure 6.5.3.1‑1 shows the retrieve entity interaction.

Figure 6.5.3.1-1: Retrieve Entity interaction

The query parameters that shall be supported are those defined in Table 6.5.3.1‑1, the request headers that shall be supported by implementations are those defined in Table 6.5.3.1‑2 and Table 6.5.3.1‑3 describes the request body and possible responses.

Table 6.5.3.1-1: Query parameters

Name	Data Type	Cardinality	Remarks
attrs	Comma separated list of strings	0..1	A synonym for a combination of the pick andq parameters. Deprecated Each String is an Attribute (Property or Relationship) name. List of Attributes to be matched by the Entity and included in the response. If the Entity does not have any of the Attributes in attrs, then a 404 Not Found shall be retrieved. If attrs is not specified, no matching is performed and all Attributes related to the Entity shall be retrieved.
pick	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name). When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.
omit	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name). When defined, the listed Entity members are removed from each Entity within the payload.
type	String	0..1	Selection of Entity Types as per clause 4.17.
geometryProperty	String	0..1	It represents a GeoProperty name. In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the "geometry" element. By default, it shall be location.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language.
containedBy	Comma separated list of URIs	0..1	List of entity ids which have previously been encountered whilst retrieving the Entity Graph. Only applicable if joinLevel is present.
join	String	0..1	The type of Linked Entity retrieval to apply (see clause 4.5.23). Allowed values: "flat", "inline", "@none" .
joinLevel	Positive Integer	0..1	Depth of Linked Entity retrieval to apply. Default is 1 Only applicable if join parameter is: "flat" or "inline".
datasetId	Comma separated list of strings	0..1	Shall be valid URIs, "@none" for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5.
entityMap	Boolean	0..1	If true, the location of the EntityMap used in the operation is returned in the response.

Table 6.5.3.1-2: Request Headers

Name	Data Type	Cardinality	Remarks
NGSILD-EntityMap	URI	0..1	If present, the EntityMap supplied is used for determining the extent of the Entity data requested during the retrieval operation. The location of the EntityMap used in the retreieval operation is returned in the response.

Table 6.5.3.1-3: Get Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Entity	1	200 OK	A response body containing the JSON-LD representation of the target entity which consists only of the selected Attributes, unless the Accept Header indicates that the Entity is to be rendered as GeoJSON. If an EntityMap has been requested, the HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource used in the operation.
	Entity	1	203 Non-Authoritative Information	As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	GeoJSON Feature	1	200 OK	If the Accept Header indicates that the Entity is to be rendered as GeoJSON, a GeoJSON Feature is returned. If an EntityMap has been requested, the HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource used in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2.
	ProblemDetails (see IETF RFC 7807 [10])	1	501 Not Implemented	It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7.

6.5.3.2 DELETE

This method is associated to the operation "Delete Entity" and shall exhibit the behaviour defined by . The Entity identifier is the value of the resource URI variable "entityId". Figure 6.5.3.2‑1 shows the delete entity interaction.

Figure 6.5.3.2-1: Delete Entity interaction

The query parameters that shall be supported are those defined in Table 6.5.3.2‑1 and Table 6.5.3.2‑2 describes the request body and possible responses.

Table 6.5.3.2-1: Query parameters

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per clause 4.17

Table 6.5.3.2-2: Delete Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	BatchOperationResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2.

6.5.3.3 PUT

This method is bound to the "Replace Entity" operation and shall exhibit the behaviour defined by clause 5.6.18. The Entity identifier is the value of the resource URI variable "entityId". The data to be updated shall be contained in the HTTP request payload body. Figure 6.5.3.3‑1 shows the Replace Entity interaction.

Figure 6.5.3.3-1: Replace Entity interaction

The query parameters that shall be supported are those defined in Table 6.5.3.3‑1 and Table 6.5.3.3‑2 describes the request body and possible responses.

Table 6.5.3.3-1: Query parameters

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per clause 4.17

Table 6.5.3.3-2: Replace Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity Fragment	1	Entity Fragment containing a complete representation of the Entity to be replaced.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No content	The entity was replaced successfully.
	BatchOperationResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2.

6.5.3.4 PATCH

This method is bound to the "Merge Entity" operation and shall exhibit the behaviour defined by clause 5.6.17. The Entity identifier is the value of the resource URI variable "entityId". The data to be updated shall be contained in the HTTP request payload body. Figure 6.5.3.4‑1 shows the Merge Entity interaction.

Figure 6.5.3.4-1: Merge Entity interaction

The query parameters that shall be supported are those defined in Table 6.5.3.4‑1 and Table 6.5.3.4‑2 describes the request body and possible responses.

Table 6.5.3.4-1: Query parameters

Name	Data Type	Cardinality	Remarks
format	String	0..1	It shall be one of: "simplified" (or its synonym "keyValues"). Where present it indicates that a simplified representation of Entities has been provided as defined by clause 4.5.4 In this case, when a merge operation applies to an existing Attribute the type field of the Attribute shall remain unchanged (any attempt to modify the type of an Attribute shall result in a BadRequest error).
options	Comma separated list of strings	0..1	An alternative mechanism to include the format parameter. Deprecated When its value includes the keyword"simplified" (or its synonym "keyValues"), this indicates that a simplified representation of Entities has been provided as defined by clause 4.5.4. If both format and options are present, the value of the format parameter shall take precedence.
type	String	0..1	Selection of Entity Types as per clause 4.17
observedAt	String	0..1	It shall be a DateTime (see clause 4.6.3). When a merge operation applies to a pre-existing Attribute which previously contained an observedAt sub-attribute, the value held in this query parameter shall be used if no specific observedAt sub-Attribute is found in the payload body.
lang	String	0..1	It represents the natural language of data held in the request. When a merge operation applies to a pre-existing LanguageProperty and the value is supplied as a string or string array in the payload body, this query parameter shall be used to determine the key within the languageMap JSON Object to update.

Table 6.5.3.4-2: Merge Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity Fragment	1	Entity Fragment containing a complete representation of the Attributes to be merged.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No content	All the Attributes were merged successfully.
	BatchOperationResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2.

6.6 Resource: entities/{entityId}/attrs/

6.6.1 Description

This resource represents all the Attributes (Properties or Relationships) of an NGSI-LD Entity.

6.6.2 Resource definition

Resource URI:

/entities/{entityId}/attrs

Resource URI variables for this resource are defined in Table 6.6.2‑1.

Table 6.6.2-1: URI variables

Name	Definition
entityId	Id (URI) of the concerned entity

6.6.3 Resource methods

6.6.3.1 POST

This method is bound to the "Append Attributes" operation and shall exhibit the behaviour defined by clause 5.6.3. The Entity identifier is the value of the resource URI variable "entityId". The data to be appended shall be contained in the HTTP request payload body. Figure 6.6.3.1‑1 shows the Append Attributes interaction.

Figure 6.6.3.1-1: Append Attributes interaction

The query parameters that shall be supported are those defined in Table 6.6.3.1‑1 and Table 6.6.3.1‑2 describes the request body and possible responses.

Table 6.6.3.1-1: Query parameters

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per clause 4.17
options	Comma separated list of strings	0..1	"noOverwrite" indicates that no attribute overwrite shall be performed.

Table 6.6.3.1-2: Post Attributes request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity Fragment	1	Entity Fragment containing a complete representation of the Attributes to be added.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No content	All the Attributes were appended successfully.
	UpdateResult	1	207 Multi-Status	Only the Attributes included in the response payload body were successfully appended. If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2.

6.6.3.2 PATCH

This method is bound to the "Update Attributes" operation and shall exhibit the behaviour defined by clause 5.6.2. The Entity identifier is the value of the resource URI variable "entityId". The data to be updated shall be contained in the HTTP request payload body. Figure 6.6.3.2‑1 shows the Update Attributes interaction.

Figure 6.6.3.2-1: Update Attributes interaction

The query parameters that shall be supported are those defined in Table 6.6.3.2‑1 and Table 6.6.3.2‑2 describes the request body and possible responses.

Table 6.6.3.2-1: Query parameters

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per clause 4.17

Table 6.6.3.2-2: Patch Attributes request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity Fragment	1	Entity Fragment containing a complete representation of the Attributes to be updated.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No content	All the Attributes were updated successfully.
	UpdateResult	1	207 Multi-Status	Only the Attributes included in the response payload body were successfully updated. If no Attributes were successfully updated the updated array of UpdateResult (see clause 5.2.18) will be empty. If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2.

6.7 Resource: entities/{entityId}/attrs/{attrId}

6.7.1 Description

This resource represents an attribute (Property or Relationship) of an NGSI-LD Entity.

6.7.2 Resource definition

Resource URI:

/entities/{entityId}/attrs/{attrId}

Resource URI variables for this resource are defined in Table 6.7.2‑1.

Table 6.7.2-1: URI variables

Name	Definition
entityId	Id (URI) of the concerned entity
attrId	Attribute name (Property or Relationship)

6.7.3 Resource methods

6.7.3.1 PATCH

This method is bound to the "Partial Attribute Update" operation and shall exhibit the behaviour defined by clause 5.6.4. The Entity identifier is the value of the resource URI variable "entityId". The attribute name is the value of the resource URI variable "attrId". The Entity Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.1‑1 shows the Partial Attribute Update interaction.

Figure 6.7.3.1-1: Partial Attribute Update interaction

The query parameters that shall be supported are those defined in Table 6.7.3.1‑1 and Table 6.7.3.2‑2 describes the request body and possible responses.

Table 6.7.3.1-1: Query parameters

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per clause 4.17

Table 6.7.3.1-2: Partial Attribute Update request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity Fragment	1	Entity Fragment containing the elements of the attribute to be updated.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content	The attribute was updated successfully.
	UpdateResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier or attribute name not known to the system, see clause 6.3.2.

6.7.3.2 DELETE

This method is associated to the operation "Delete Attribute" and shall exhibit the behaviour defined by clause 5.6.5. The Entity identifier is the value of the resource URI variable "entityId". The attribute name is the value of the resource URI variable "attrId". Figure 6.7.3.2‑1 shows the Delete Attribute interaction, Table 6.7.3.2‑1 shows the delete parameters to be supported and Table 6.7.3.2‑2 describes the request body and possible responses.

Figure 6.7.3.2-1: Delete Attribute interaction

Table 6.7.3.2-1: Delete parameters

Name	Data Type	Cardinality	Remarks
deleteAll	Boolean	0..1	If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, the default Attribute instance is deleted.
type	String	0..1	Selection of Entity Types as per clause 4.17.
datasetId	String	0..1	Shall be a valid URI. Specifies the datasetId of the dataset to be deleted.

Table 6.7.3.2-2: Delete Attribute request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	UpdateResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) or attribute name not known to the system. see clause 6.3.2.

6.7.3.3 PUT

This method is bound to the "Replace Attribute" operation and shall exhibit the behaviour defined by clause 5.6.19. The Entity identifier is the value of the resource URI variable "entityId". The attribute name is the value of the resource URI variable "attrId". The Attribute Fragment shall be contained in the HTTP request payload body. Figure 6.7.3.3‑1 shows the Replace Attribute interaction.

Figure 6.7.3.3-1: Replace Attribute interaction

The query parameters that shall be supported are those defined in Table 6.7.3.3‑1 and Table 6.7.3.3‑2 describes the request body and possible responses.

Table 6.7.3.3-1: Query parameters

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per clause 4.17

Table 6.7.3.3-2: Replace Attribute request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Attribute Fragment	1	Attribute Fragment replacing the previous data.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content	The attribute was replaced successfully.
	UpdateResult	1	207 Multi-Status	If the entity input data matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a UpdateResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier or attribute name not known to the system, see clause 6.3.2.

6.8 Resource: csourceRegistrations/

6.8.1 Description

This resource represents the context source registrations known to an NGSI-LD system.

6.8.2 Resource definition

Resource URI:

/csourceRegistrations/

6.8.3 Resource methods

6.8.3.1 POST

This method is bound to the operation "Register Context Source" and shall exhibit the behaviour defined by clause 5.9.2, taking the context source registration to be created from the HTTP request payload body. Figure 6.8.3.1‑1 shows the Register Context Source interaction and Table 6.8.3.1‑1 describes the request body and possible responses.

Figure 6.8.3.1-1: Register Context Source interaction

Table 6.8.3.1-1: Patch Attribute request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	CSourceRegistration	1	Payload body in the request contains a JSON-LD object which represents the context source registration that is to be created.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	201 Created	The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created context source registration resource.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	409 Conflict	It is used to indicate that the context source registration already exists, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	422 Unprocessable Context Source Registration	It is used to indicate that the operation is not available see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.8.3.2 GET

This method is associated to the operation "Query Context Source Registrations" and shall exhibit the behaviour defined by clause 5.10.2, i.e. the parameters in the request describe entity related information, but instead of directly providing this entity information, the context source registration data, which describes context sources that can possibly provide the information, are returned as part of the HTTP response payload body. Figure 6.8.3.2‑1 shows the Query Context Source Registrations interaction.

Figure 6.8.3.2-1: Query Context Source Registrations interaction

The query parameters that shall be supported by implementations are those defined in Table 6.8.3.2‑1 and Table 6.8.3.2‑2 describes the request body and possible responses.

Table 6.8.3.2-1: Query parameters

Name	Data Type	Cardinality	Remarks
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
type	String	0..1 At least one among: type, attrs, q, or georel shall be present.	Selection of Entity Types as per clause 4.17.
idPattern	Regular expression as defined by [11]	0..1	Regular expression that shall be matched by entity ids satisfying the query
attrs	Comma separated list strings	0..1 At least one among: type, attrs, q, or georel shall be present.	Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.
q	String	0..1 At least one among: type, attrs, q, or georel shall be present.	Query as per clause 4.9.
csf	String	0..1	Context Source filter as per clause 4.9.
geometry	String	0..1 It shall be 1 if georel or coordinates are present. At least one among: type, attrs, q, or georel shall be present.	Geometry as per clause 4.10. It is part of geoquery.
georel	String	0..1 It shall be 1 if geometry or coordinates are present.	Geo relationship as per clause 4.10. It is part of geoquery.
coordinates	String	0..1 It shall be one if geometry or georel are present.	Coordinates serialized as a string as per clause 4.10. It is part of geoquery.
geoproperty	String	0..1 It shall be ignored if no geoquery is present.	It represents the name of the Property that contains the geospatial data that will be used to resolve the geoquery.
timeproperty	String	0..1 It shall be ignored if no temporal query is present.	It represents a Temporal Property name. Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is "observedAt". (See clause 4.8).
timerel	String	0..1	It represents the temporal relationship as defined by clause 4.1. Allowed values: "before", "after", "between".
timeAt	String	0..1	It represents the timeAt parameter as defined by clause 4.1. It shall be a DateTime. Cardinality shall be 1 if timerel is present.
endTimeAt	String	0..1	It represents the endTimeAt parameter as defined by clause 4.1. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between".
geometryProperty	String	0..1	It represents a Property name. In the case of GeoJSON Entity representation, this parameter indicates which GeoProperty to use for the toplevel geometry field.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language.
scopeQ	String	0..1	Scope query (see clause 4.19).

Table 6.8.3.2-2: Get Context Source Registrations request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	CSourceRegistration[]	1	200 OK	A response body containing the query result as an array of context source registrations.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.9 Resource: csourceRegistrations/{registrationId}

6.9.1 Description

This resource represents the context source registration, identified by registrationId, known to an NGSI-LD system.

6.9.2 Resource definition

Resource URI:

/csourceRegistrations/{registrationId}

Resource URI variables for this resource are defined in Table 6.9.2‑1.

Table 6.9.2-1: URI variables

Name	Definition
registrationId	Id (URI) of the context source registration

6.9.3 Resource methods

6.9.3.1 GET

This method is associated with the operation "Retrieve Context Source Registration" and shall exhibit the behaviour defined by clause 5.10.1. The registration identifier is the value of the resource URI variable "registrationId". Figure 6.9.3.1‑1 shows the Retrieve Context Source Registration interaction and Table 6.9.3.1‑1 describes the request body and possible responses.

Figure 6.9.3.1-1: Retrieve Context Source Registration interaction

Table 6.9.3.1-1: Get Context Source Registration request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	CSourceRegistration	1	200 OK	A response body containing the JSON-LD representation of the target context source registration.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a context source registration identifier (URI) not known to the system, see clause 6.3.2.

6.9.3.2 PATCH

This method is bound to the "Update Context Source Registration" operation and shall exhibit the behaviour defined by clause 5.9.3. The context source registration identifier is the value of the resource URI variable "registrationId". The context source registration to be updated shall be contained in the HTTP request payload body. Figure 6.9.3.2‑1 shows the Update Context Source Registration interaction and Table 6.9.3.2‑1 describes the request body and possible responses.

Figure 6.9.3.2-1: Update Context Source Registration interaction

Table 6.9.3.2-1: Patch Context Source Registration request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	CSourceRegistration Fragment	1	Payload body in the request contains a JSON-LD object which represents the context source registration that is to be updated.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content	The context source registration was successfully updated.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a context source registration identifier not known to the system, see clause 6.3.2.

6.9.3.3 DELETE

This method is associated to the operation "Delete Context Source Registration" and shall exhibit the behaviour defined by clause 5.9.4. The context source registration identifier is the value of the resource URI variable "registrationId". Figure 6.9.3.3‑1 shows the Delete Context Source Registration interaction and Table 6.9.3.3‑1 describes the request body and possible responses.

Figure 6.9.3.3-1: Delete Context Source Registration interaction

Table 6.9.3.3-1: Delete Context Source Registration request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a context source registration identifier (URI) not known to the system, see clause 6.3.2.

6.10 Resource: subscriptions/

6.10.1 Description

This resource represents the subscriptions known to an NGSI-LD system.

6.10.2 Resource definition

Resource URI:

/subscriptions/

6.10.3 Resource methods

6.10.3.1 POST

This method is bound to the operation "Create Subscription" and shall exhibit the behaviour defined by clause 5.8.1, taking the subscription to be created from the HTTP request payload body. Figure 6.10.3.1‑1 shows the Create Subscription interaction and Table 6.10.3.1‑1 describes the request body and possible responses.

Figure 6.10.3.1-1: Create Subscription interaction

Table 6.10.3.1-1: Post Subscription request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Subscription	1	Payload body in the request contains a JSON-LD object which represents the subscription that is to be created.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	201 Created	The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created subscription resource.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	409 Conflict	It is used to indicate that the subscription already exists see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.10.3.2 GET

This method is associated to the operation "Query Subscriptions" and shall exhibit the behaviour defined by clause 5.8.4, providing the subscription data as part of the HTTP response payload body. Figure 6.10.3.2‑1 shows the Query Subscriptions interaction.

Figure 6.10.3.2-1: Query Subscriptions interaction

The query parameters that shall be supported by implementations are those defined in Table 6.10.3.2‑1 and Table 6.10.3.2‑2 describes the request body and possible responses.

Table 6.10.3.2-1: Query parameters

Name	Data Type	Cardinality	Remarks
limit	Number	0..1	Maximum number of subscriptions to be retrieved

Table 6.10.3.2-2: Get Subscriptions request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Subscription[]	1	200 OK	A response body containing a list of subscriptions.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.11 Resource: subscriptions/{subscriptionId}

6.11.1 Description

This resource represents a subscription known to an NGSI-LD system.

6.11.2 Resource definition

Resource URI:

/subscriptions/{subscriptionId}

Resource URI variables for this resource are defined in Table 6.11.2‑1.

Table 6.11.2-1: URI variables

Name	Definition
subscriptionId	Id (URI) of the concerned subscription

6.11.3 Resource methods

6.11.3.1 GET

This method is associated to the operation "Retrieve Subscription" and shall exhibit the behaviour defined by clause 5.8.3. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 6.11.3.1‑1 shows the Retrieve Subscription interaction and Table 6.11.3.1‑1 describes the request body and possible responses.

Figure 6.11.3.1-1: Retrieve Subscription interaction

Table 6.11.3.1-1: Get Subscription request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Subscription	1	200 OK	A response body containing the JSON-LD representation of the target subscription.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2.

6.11.3.2 PATCH

This method is associated to the operation "Update Subscription" and shall exhibit the behaviour defined by clause 5.8.2. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 6.11.3.2‑1 shows the Update Subscription interaction and Table 6.11.3.2‑1 describes the request body and possible responses.

Figure 6.11.3.2-1: Update Subscription interaction

Table 6.11.3.2-1: Patch Subscription request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Subscription Fragment	1	Subscription Fragment including id, type and any other subscription field to be changed
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2.

6.11.3.3 DELETE

This method is associated to the operation "Delete Subscription" and shall exhibit the behaviour defined by clause 5.8.5. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 6.11.3.3‑1 shows the Delete Subscription interaction and Table 6.11.3.3‑1 describes the request body and possible responses.

Figure 6.11.3.3-1: Delete Subscription interaction

Table 6.11.3.3-1: Delete Subscription request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2.

6.12 Resource: csourceSubscriptions/

6.12.1 Description

This resource represents the context source registration subscriptions known to an NGSI-LD system.

6.12.2 Resource definition

Resource URI:

/csourceSubscriptions/

6.12.3 Resource methods

6.12.3.1 POST

This method is bound to the operation "Create Context Source Registration Subscription" and shall exhibit the behaviour defined by clause 5.11.2, taking the context source registration subscription to be created from the HTTP request payload body. Figure 6.12.3.1‑1 shows the Create Context Source Registration Subscription interaction and Table 6.12.3.1‑1 describes the request body and possible responses.

Figure 6.12.3.1-1: Create Context Source Registration Subscription interaction

Table 6.12.3.1-1: Post Context Source Registration Subscription request body
and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Subscription	1	Payload body in the request contains a JSON-LD object which represents the context source registration subscription that is to be created.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	201 Created	The HTTP response shall include a "Location" HTTP header that contains the resource URI of the created context source registration subscription resource.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	409 Conflict	It is used to indicate that the context source registration subscription already exists, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.12.3.2 GET

This method is associated to the operation "Query Context Source Registration Subscriptions" and shall exhibit the behaviour defined by clause 5.11.5, providing the context source registration subscription data as part of the HTTP response payload body. Figure 6.12.3.2‑1 shows the Query Context Source Registration Subscriptions interaction.

Figure 6.12.3.2-1: Query Context Source Registration Subscriptions interaction

The query parameters that shall be supported by implementations are those defined in Table 6.12.3.2‑1 and Table 6.12.3.2‑2 describes the request body and possible responses.

Table 6.12.3.2-1: Query parameters

Name	Data Type	Cardinality	Remarks
limit	Number	0..1	Maximum number of subscriptions to be retrieved

Table 6.12.3.2-2: Get Context Source Registration Subscriptions request body
and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Subscription[]	1	200 OK	A response body containing a list of context source registration subscriptions.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.13 Resource: csourceSubscriptions/{subscriptionId}

6.13.1 Description

This resource represents the context source registration subscription, identified by subscriptionId, known to an NGSI-LD system.

6.13.2 Resource definition

Resource URI:

/csourceSubscriptions/{subscriptionId}

Resource URI variables for this resource are defined in Table 6.13.2‑1.

Table 6.13.2-1: URI variables

Name	Definition
subscriptionId	Id (URI) of the concerned context source registration subscription

6.13.3 Resource methods

6.13.3.1 GET

This method is associated to the operation "Retrieve Context Source Registration Subscription" and shall exhibit the behaviour defined by clause 5.11.4. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 6.13.3.1‑1 shows the Retrieve Context Source Registration interaction and Table 6.13.3.1‑1 describes the request body and possible responses.

Figure 6.13.3.1-1: Retrieve Context Source Registration Subscription interaction

Table 6.13.3.1-1: Get Context Source Registration Subscription request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Subscription	1	200 OK	A response body containing the JSON-LD representation of the target context source registration subscription.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2.

6.13.3.2 PATCH

This method is associated to the operation "Update Context Source Registration Subscription" and shall exhibit the behaviour defined by clause 5.11.3. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 6.13.3.2‑1 shows the Update Context Source Registration Subscription interaction and Table 6.13.3.2‑1 describes the request body and possible responses.

Figure 6.13.3.2-1: Update Context Source Registration Subscription interaction

Table 6.13.3.2-1: Patch Context Source Registration Subscription request body
and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Subscription Fragment	1	Subscription Fragment including id, type and any other context source registration subscription field to be changed
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2.

6.13.3.3 DELETE

This method is associated to the operation "Delete Context Source Registration Subscription" and shall exhibit the behaviour defined by clause 5.11.6. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 6.13.3.3‑1 shows the Delete Context Source Registration Subscription interaction and Table 6.13.3.3‑1 describes the request body and possible responses.

Figure 6.13.3.3-1: Delete Context Source Registration Subscription interaction

Table 6.13.3.3-1: Delete Context Source Registration Subscription request body
and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided a subscription identifier (URI) not known to the system, see clause 6.3.2.

6.14 Resource: entityOperations/create

6.14.1 Description

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity creation for the NGSI-LD API.

6.14.2 Resource definition

Resource URI:

/entityOperations/create

6.14.3 Resource methods

6.14.3.1 POST

This method is associated to the operation "Batch Entity Creation" and shall exhibit the behaviour defined by clause 5.6.7. Figure 6.14.3.1‑1 shows the operation interaction and Table 6.14.3.1‑1 describes the request body and possible responses.

Figure 6.14.3.1-1: Batch Entity Creation Interaction

Table 6.14.3.1-1: Batch Entity Creation Interaction and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity[]	1	Array of entities to be created
Response Body	Data Type	Cardinality	Response Code	Remarks
	String[]	1	201 Created	If all entities have been successfully created, an array of Strings containing URIs is returned in the response. Each URI represents the Entity ID of a created entity. There is no restriction as to the order of the Entity IDs.
	BatchOperationResult	1	207 Multi-Status	If only some or none of the entities have been successfully created, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully created entities, while the second array (errors) contains information about the error for each of the entities that could not be created. There is no restriction as to the order of the Entity IDs in the arrays. If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.15 Resource: entityOperations/upsert

6.15.1 Description

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity creation or update for the NGSI-LD API.

6.15.2 Resource definition

Resource URI:

/entityOperations/upsert

6.15.3 Resource methods

6.15.3.1 POST

This method is associated to the operation "Batch Entity Creation or Update (Upsert)" and shall exhibit the behaviour defined by clause 5.6.8. Figure 6.15.3.1‑1 shows the operation interaction and Table 6.15.3.1‑1 describes the request body and possible responses.

The options query parameter for this request can take the following values:

"replace". Indicates that all the existing Entity content shall be replaced (default mode);
"update". Indicates that existing Entity content shall be updated.

Figure 6.15.3.1-1: Batch Entity Creation or Update Interaction

Table 6.15.3.1-1: Batch Entity Creation or Update Interaction and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity[]	1	Array of entities to be created/updated
Response Body	Data Type	Cardinality	Response Code	Remarks
	String[]	1	201 Created	If all entities not existing prior to this request have been successfully created and the others have been successfully updated, an array of String (with the URIs representing the Entity IDs of the created entities only) is returned in the response. There is no restriction as to the order of the Entity IDs. The merely updated entities do not take part in the response (corresponding to 204 No Content returned in the case of updates).
	N/A	N/A	204 No Content	If all entities already existed and are successfully updated, there is no payload body in the response.
	BatchOperationResult	1	207 Multi-Status	If only some or none of the entities have been successfully created or updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully created or updated entities, while the second array (errors) contains information about the error for each of the entities that could not be created or updated. There is no restriction as to the order of the Entity IDs in the arrays. If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.16 Resource: entityOperations/update

6.16.1 Description

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity update for the NGSI-LD API.

6.16.2 Resource definition

Resource URI:

/entityOperations/update

6.16.3 Resource methods

6.16.3.1 POST

This method is associated to the operation "Batch Entity Update" and shall exhibit the behaviour defined by clause 5.6.9. Figure 6.16.3.1‑1 shows the operation interaction and Table 6.16.3.1‑1 describes the request body and possible responses.

The options query parameter for this request can take the following values:

"noOverwrite". Indicates that no attribute overwrite shall be performed.

Figure 6.16.3.1-1: Batch Entity Update Interaction

Table 6.16.3.1-1: Batch Entity Update Interaction and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity[]	1	Array of Entities to be updated
Response Body	Data Type	Cardinality	Response Code	Remarks
	N/A	N/A	204 No Content	If all entities have been successfully updated, there is no payload body in the response.
	BatchOperationResult	1	207 Multi-Status	If only some or none of the entities have been successfully updated, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully updated entities, while the second array (errors) contains information about the error for each of the entities that could not be updated. There is no restriction as to the order of the Entity IDs in the arrays. If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.17 Resource: entityOperations/delete

6.17.1 Description

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity deletion for the NGSI-LD API.

6.17.2 Resource definition

Resource URI:

/entityOperations/delete

6.17.3 Resource methods

6.17.3.1 POST

This method is associated to the operation "Batch Entity Delete" and shall exhibit the behaviour defined by clause 5.6.10. Figure 6.17.3.1‑1 shows the operation interaction and Table 6.17.3.1‑1 describes the request body and possible responses.

Figure 6.17.3.1-1: Batch Entity Delete Interaction

Table 6.17.3.1-1: Batch Entity Delete Interaction and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	String[]	1	Array of String (URIs representing Entity IDs) to be deleted
Response Body	Data Type	Cardinality	Response Code	Remarks
	N/A	N/A	204 No Content	If all entities existed and have been successfully deleted, there is no payload body in the response.
	BatchOperationResult	1	207 Multi-Status	If some or all of the entities have not been successfully deleted, or did not exist, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully deleted entities, while the second array (errors) contains information about the error for each of the entities that could not be deleted. There is no restriction as to the order of the Entity IDs in the arrays. If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.18 Resource: temporal/entities/

6.18.1 Description

This resource represents the Temporal Evolution of Entities known to an NGSI-LD system.

6.18.2 Resource definition

Resource URI:

/temporal/entities/

6.18.3 Resource methods

6.18.3.1 POST

This method is associated to the operation "Create or Update Temporal Evolution of an Entity" and shall exhibit the behaviour defined by clause 5.6.11, taking the temporal representation of Entity to be created from the HTTP request payload body. Figure 6.18.3.1‑1 shows this interaction and Table 6.18.3.1‑1 describes the request body and possible responses.

Figure 6.18.3.1-1: Create or Update Temporal Evolution of an Entity interaction

Table 6.18.3.1-1: Post EntityTemporal request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	EntityTemporal	1	Payload body in the request contains a JSON-LD object which represents the temporal representation of the Entity that is to be created (or updated).
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	201 Created	Upon creation success, the HTTP response shall include a "Location" HTTP header that contains the resource URI of the created entity resource.
	N/A	N/A	204 No Content	Upon update success.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail member should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	422 Unprocessable Entity	It is used to indicate that the operation is not available, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.18.3.2 GET

This method is associated to the operation "Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by clause 5.7.4, providing the Temporal Evolution of the matching Entities as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Query Temporal Evolution of Entities" operations via POST is defined in clause 6.24. Figure 6.18.3.2‑1 shows this interaction.

Figure 6.18.3.2-1: Query Temporal Evolution of Entities interaction

The query parameters that shall be supported by implementations are those defined in Table 6.18.3.2‑1 and Table 6.18.3.2‑2 describes the request body and possible responses.

Table 6.18.3.2-1: Temporal Evolution Query parameters

Name	Data Type	Cardinality	Remarks
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
type	String	0..1 It shall be 1 if attrs is not present, unless the execution of the request is limited to local scope (see clause 5.5.13).	Selection of Entity Types as per clause 4.17. "" is also allowed as a value and local* is implicitly set to true and shall not be explicitly set tofalse.
idPattern	Regular expression as defined by [11]	0..1	Regular expression that shall be matched by entity ids.
attrs	Comma separated list of strings	0..1 It shall be 1 if type is not present, unless the execution of the request is limited to local scope (see clause 5.5.13).	A synonym for a combination of the pick andq parameters. Deprecated Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.
pick	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or an Attribute name). When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.
omit	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or an Attribute name). When defined, the listed Entity members are removed from each Entity within the payload.
q	String	0..1	Query as per clause 4.9.
expandValues	Comma separated list of strings	0..1	Each String is an Attribute (Property or Relationship) name. List of Attributes whose values shall be expanded into URIs according to the supplied @context prior to executing a query. It is part of query.
jsonKeys	Comma separated list of strings	0..1	Each String is an Attribute (Property or Relationship) name. 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.
csf	String	0..1	Context Source filter as per clause 4.9.
geometry	String	0..1 It shall be 1 if georel or coordinates are present	Geometry as per clause 4.10. It is part of geoquery.
georel	String	0..1 It shall be 1 if geometry or coordinates are present	Geo relationship as per clause 4.10. It is part of geoquery.
coordinates	String	0..1 It shall be one if georel or geometry are present	Coordinates serialized as a string as per clause 4.10. It is part of geoquery.
geoproperty	String	0..1 It shall be ignored if no geoquery is present	The name of the GeoProperty that contains the geospatial data that will be used to resolve the geoquery. By default, will be location. (See clause 4.7).
timeproperty	String	0..1	It represents a Temporal Property name. Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is "observedAt". (See clause 4.8).
timerel	String	1	It represents the temporal relationship as defined by clause 4.11. Allowed values: "before", "after", "between".
timeAt	String	1	representing the timeAt parameter as defined by clause 4.11. It shall be a DateTime.
endTimeAt	String	0..1	It representing the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between".
lastN	Positive integer	0..1	Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language.
aggrMethods	Comma separated list of strings	0..1 It shall be 1 if aggregatedValues is present in the options parameter	Each String represents an aggregation method, as defined by clause 4.5.19. Only applicable if "aggregatedValues" is present in the options parameter.
aggrPeriodDuration	String	0..1	It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. Only applicable if "aggregatedValues" is present in the options parameter.
scopeQ	String	0..1	Scope query (see clause 4.19)
datasetId	Comma separated list of strings	0..1	Shall be valid URIs, "@none" for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5.
entityMap	Boolean	0..1	If true, the location of the EntityMap used in the operation is returned in the response.
entityMapLifetime	String	0..1	Suggested duration, represented in ISO 8601 format [17], for which the requester wants the EntityMap to exist. The actual expiresAt time of the EntityMap shall be set by the Context Broker or Context Source, possibly overriding the requested duration. Only applicable if entityMap is set to true.
splitEntities	Boolean	0..1	If true it is assumed that single Entities are distributed between different Context Brokers and/or Context Sources and this has to be taken into account when 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. The parameter does not apply in case local is true. The default value should be decided by implementation; it should be configurable.

Table 6.18.3.2-2: Query Entities History request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityTemporal[]	1	200 OK 201 Created (in case an EntityMap has been (re)created)	A response body containing the query result as a list of temporal representation of Entities. If an EntityMap has been requested, the HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource used in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.19 Resource: temporal/entities/{entityId}

6.19.1 Description

This resource is associated to the Temporal Evolution of an Entity known to an NGSI-LD system.

6.19.2 Resource definition

Resource URI:

/temporal/entities/{entityId}

Resource URI variables for this resource are defined in Table 6.19.2‑1.

Table 6.19.2-1: URI variables

Name	Definition
entityId	Id (URI) of the entity to be retrieved

6.19.3 Resource methods

6.19.3.1 GET

This method is associated to the operation "Retrieve Temporal Evolution of an Entity" and shall exhibit the behaviour defined by clause 5.7.3. The Entity identifier is the value of the resource URI variable entityId. Figure 6.19.3.1‑1 shows the retrieve temporal representation of an entity interaction.

Figure 6.19.3.1-1: Retrieve Temporal Evolution of an Entity interaction

The query parameters that shall be supported are those defined in Table 6.19.3.1‑1 and Table 6.19.3.1‑2 describes the request body and possible responses.

Table 6.19.3.1-1: Query parameters

Name	Data Type	Cardinality	Remarks
attrs	Comma separated list of strings	0..1	A synonym for a combination of the pick andq parameters. Deprecated Each String is an Attribute (Property or Relationship) name. List of Attributes to be retrieved. If not specified, all Attributes related to the temporal representation of an Entity shall be retrieved.
pick	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or an Attribute name). When defined, every Entity within the payload body is reduced down to only contain the listed Entity members.
omit	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or an Attribute name). When defined, the listed Entity members are removed from each Entity within the payload.
timeproperty	String	0..1	It represents a Temporal Property name. Allowed values: "observedAt", "createdAt", "modifiedAt" and "deletedAt". If not specified, the default is "observedAt". (See clause 4.8).
timerel	String	0..1 It shall be 1 if timeAt is present	It represents the Temporal Relationship as defined by clause 4.11. Allowed values: "before", "after", "between".
timeAt	String	0..1 It shall be 1 if timerel is present	It represents the timeAt parameter as defined by clause 4.11. It shall be a DateTime.
endTimeAt	String	0..1 It shall be 1 if timerel is equal to "between"	It represents the endTimeAt parameter as defined by clause 4.11. It shall be a DateTime.
lastN	Positive integer	0..1	Only the last n Attribute instances (under the concerned time interval) shall be retrieved.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce languageMaps to a string or string array property in a single preferred language.
aggrMethods	Comma separated list of strings	0..1 It shall be 1 if aggregatedValues is present in the options parameter	Each String represents the aggregation methods as defined by clause 4.5.19. Only applicable if "aggregatedValues" is present in the options parameter.
aggrPeriodDuration	String	0..1	It represents the duration of each period used for the aggregation as defined by clause 4.5.19. If not specified, it defaults to a duration of 0 seconds and is interpreted as a duration spanning the whole time-range specified by the temporal query. Only applicable if "aggregatedValues" is present in the options parameter.
datasetId	Comma separated list of strings	0..1	Shall be valid URIs, "@none" for including the default Attribute instances. Specifies the datasetIds of the Attribute instances to be selected for each matched Attribute as per clause 4.5.5.

Table 6.19.3.1-2: Get Temporal Evolution of an Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityTemporal	1	200 OK	A response body containing the JSON-LD temporal representation of the target Entity containing the selected Attributes.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2.

6.19.3.2 DELETE

This method is associated to the operation "Delete Temporal Evolution of an Entity" and shall exhibit the behaviour defined by clause 5.6.16. The Entity identifier is the value of the resource URI variable entityId. Figure 6.19.3.2‑1 shows the delete entity interaction and Table 6.19.3.2‑1 describes the request body and possible responses.

Figure 6.19.3.2-1: Delete Temporal Evolution of an Entity interaction

Table 6.19.3.2-1: Delete Temporal Evolution of an Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2.

6.20 Resource: temporal/entities/{entityId}/attrs/

6.20.1 Description

This resource represents all the Attributes (Properties or Relationships) of a Temporal Evolution of an Entity.

6.20.2 Resource definition

Resource URI:

/temporal/entities/{entityId}/attrs/

Resource URI variables for this resource are defined in Table 6.20.2‑1.

Table 6.20.2-1: URI variables

Name	Definition
entityId	Id (URI) of the concerned entity

6.20.3 Resource methods

6.20.3.1 POST

This method is bound to the "Add Attributes to Temporal Evolution of an Entity" operation and shall exhibit the behaviour defined by clause 5.6.12. The Entity identifier is the value of the resource URI variable entityId. The data to be added shall be contained in the HTTP request payload body. Figure 6.20.3.1‑1 shows the Add Attributes interaction and Table 6.20.3.1‑1 describes the request body and possible responses.

Figure 6.20.3.1-1: Add Attributes to Temporal Evolution of an Entity interaction

Table 6.20.3.1-1: Add Attributes to Temporal Evolution of
an Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	EntityTemporal Fragment	1	EntityTemporal Fragment containing a complete representation of the Attribute instances to be added.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No content	All the Attributes were added successfully.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) not known to the system, see clause 6.3.2.

6.21 Resource: temporal/entities/{entityId}/attrs/{attrId}

6.21.1 Description

This resource represents an Attribute (Property or Relationship) of a Temporal Evolution of an Entity.

6.21.2 Resource definition

Resource URI:

/temporal/entities/{entityId}/attrs/{attrId}

Resource URI variables for this resource are defined in Table 6.21.2‑1.

Table 6.21.2-1: URI variables

Name	Definition
entityId	Id (URI) of the concerned entity
attrId	Attribute name (Property or Relationship)

6.21.3 Resource methods

6.21.3.1 DELETE

This method is associated to the operation "Delete Attribute from Temporal Evolution of an Entity" and shall exhibit the behaviour defined by clause 5.6.13. The Entity identifier is the value of the resource URI variable entityId. The Attribute name is the value of the resource URI variable attrId. Figure 6.21.3.1‑1 shows the "Delete Attribute from Temporal Evolution of an Entity" interaction, Table 6.21.3.1‑1 shows the delete parameters to be supported and Table 6.21.3.1‑2 describes the request body and possible responses.

Figure 6.21.3.1-1: Delete Attribute from Temporal Evolution
of an Entity interaction

Table 6.21.3.1-1: Delete parameters

name	Data Type	Cardinality	Remarks
deleteAll	Boolean	0..1	If true, all attribute instances are deleted. Otherwise (default) only the Attribute instance specified by the datasetId is deleted. In case neither the deleteAll flag nor a datasetId is present, the default Attribute instance is deleted.
datasetId	String	0..1	Shall be a valid URI. Specifies the datasetId of the dataset to be deleted.

Table 6.21.3.1-2: Delete Attribute from Temporal Evolution of
an Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) or Attribute name not known to the system. See clause 6.3.2.

6.22 Resource: temporal/entities/{entityId}/attrs/{attrId}/ {instanceId}

6.22.1 Description

This resource represents an Attribute (Property or Relationship) instance of a Temporal Evolution of an Entity.

6.22.2 Resource definition

Resource URI:

/temporal/entities/{entityId}/attrs/{attrId}/{instanceId}

Resource URI variables for this resource are defined in Table 6.22.2‑1.

Table 6.22.2-1: URI variables

Name	Definition
entityId	Id (URI) of the concerned entity
attrId	Attribute name (Property or Relationship)
instanceId	Id (URI) identifying a particular Attribute instance

6.22.3 Resource methods

6.22.3.1 PATCH

This method is associated to the operation "Modify attribute instance from Temporal Evolution of an Entity" and shall exhibit the behaviour defined by clause 5.6.14. The Entity identifier is the value of the resource URI variable entityId. The attribute name is the value of the resource URI variable attrId. The instance identifier is the value of the resource URI variable instanceId. Figure 6.22.3.1‑1 shows the Modify Attribute instance interaction and Table 6.22.3.1‑1 describes the request body and possible responses.

Figure 6.22.3.1-1: Modify Attribute instance from Temporal Evolution interaction

Table 6.22.3.1-1: Modify Attribute instance from
Temporal Evolution request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	EntityTemporal Fragment	1	EntityTemporal Fragment containing a complete representation of the Attribute instance to be replaced.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See clause 6.3.2.

6.22.3.2 DELETE

This method is associated to the operation "Delete Attribute instance from Temporal Evolution of an Entity" and shall exhibit the behaviour defined by clause 5.6.15. The Entity identifier is the value of the resource URI variable entityId. The Attribute name is the value of the resource URI variable attrId. The instance identifier is the value of the resource URI variable instanceId. Figure 6.22.3.2‑1 shows the Delete Attribute instance interaction and Table 6.22.3.2‑1 describes the request body and possible responses.

Figure 6.22.3.2-1: Delete Attribute instance from Temporal Evolution of an Entity interaction

Table 6.22.3.2-1: Delete Attribute instance from
Temporal Evolution of an Entity request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an Entity identifier (URI), attribute name or instance identifier not known to the system. See clause 6.3.2.

6.23 Resource: entityOperations/query

6.23.1 Description

A sub-resource, pertaining to the entityOperations/ resource, intended to enable querying for entities by means of a POST method. The behaviour of this clause mirrors the one in clause 6.4.3.2, which performs the "Query Entity" operation (defined by clause 5.7.2) by means of a GET method. The reason to provide an alternative via POST is that, using GET:

The client may end up assembling very long URLs, due to the URI parameters for id, q‚ type, attrs, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length.
There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.

6.23.2 Resource definition

Resource URI:

/entityOperations/query

6.23.3 Resource methods

6.23.3.1 POST

This method is associated to the operation "Query Entities" and shall exhibit the behaviour defined by clause 5.7.2. Figure 6.23.3.1‑1 shows the operation interaction and Table 6.23.3.1‑1 describes the request body and possible responses.

Figure 6.23.3.1-1: Query Entity via POST Interaction

Table 6.23.3.1-1: Query Entity via POST Interaction and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Query	1	Payload body in the request contains a JSON-LD object which represents the query to be performed.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Entity[]	1	200 OK 201 Created (in case an EntityMap has been (re)created)	A response body containing the query result as a list of Entities. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	GeoJSON FeatureCollection	1	200 OK 201 Created (in case an EntityMap has been (re)created)	If the Accept Header indicates that the Entities are to be rendered as GeoJSON, a response body containing the query result as GeoJSON FeatureCollection is returned. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.24 Resource: temporal/entityOperations/query

6.24.1 Description

A sub-resource, pertaining to the temporal/entityOperations/ resource, intended to enable temporal querying for entities by means of a POST method. The behaviour of this clause mirrors the one in clause 6.18.3.2, which performs the "Query Temporal Evolution of Entities" (defined by clause 5.7.4) operation by means of a GET method. The reason to provide an alternative via POST is that, using GET:

The client may end up assembling very long URLs, due to the URI parameters for id, q‚ type, attrs, etc., being included in the URL. Problems with too long URLs may arise with some applications that cut URLs to a maximum length.
There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.

6.24.2 Resource definition

Resource URI:

/temporal/entityOperations/query

6.24.3 Resource methods

6.24.3.1 POST

This method is associated to the operation "Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by clause 5.7.4. Figure 6.24.3.1‑1 shows the operation interaction and Table 6.24.3.1‑1 describes the request body and possible responses.

Figure 6.24.3.1-1: Temporal Query Entity via POST Interaction

Table 6.24.3.1-1: Temporal Query Entity via POST Interaction request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Query	1	Payload body in the request contains a JSON-LD object which represents the query to be performed.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityTemporal[]	1	200 OK 201 Created (in case an EntityMap has been (re)created)	A response body containing the query result as a list of Entities. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.25 Resource: types/

6.25.1 Description

This resource represents the entity types available in an NGSI-LD system.

6.25.2 Resource definition

Resource URI:

/types/

6.25.3 Resource methods

6.25.3.1 GET

This method is associated to the operations "Retrieve Available Entity Types" and "Retrieve Details of Available Entity Types" (if the details parameter is set to true) and shall exhibit the behaviour defined by clauses 5.7.5 and 5.7.6 respectively.

Figure 6.25.3.1-1: Retrieve Available Entity Types interaction

The request parameters that shall be supported are those defined in Table 6.25.3.1‑1 and Table 6.25.3.1‑2 describes the request body and possible responses.

Table 6.25.3.1-1: Retrieve Available Entity Types: optional parameter

Name	Data Type	Cardinality	Remarks
details	Boolean	0..1	If true, then detailed entity type information represented as an array with elements of the Entity Type data structure (clause 5.2.25) is to be returned

Table 6.25.3.1-2: Retrieve Available Entity Types request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityTypeList	1	200 OK	A response body containing the JSON-LD representation of the EntityTypeList (clause 5.2.24) is to be returned, unless details=true is specified.
	EntityType[]	1	200 OK	If details=true is specified, a response body containing a JSON-LD array with elements of the EntityType data structure (clause 5.2.25) is to be returned.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.26 Resource: types/{type}

6.26.1 Description

This resource represents the specified entity type for which entity instances are available in an NGSI-LD system.

6.26.2 Resource definition

Resource URI:

/types/{type}

Resource URI variables for this resource are defined in Table 6.26.2‑1.

Table 6.26.2-1: URI variables

Name	Definition
type	Name of the entity type for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided.

6.26.3 Resource methods

6.26.3.1 GET

This method is associated to the operation "Retrieve Available Entity Type Information" and shall exhibit the behaviour defined by clause 5.7.7. The entity type is the value of the resource URI variable "type". Figure 6.26.3.1‑1 shows the retrieve available entity type interaction.

Figure 6.26.3.1-1: Retrieve Available Entity Type interaction

Table 6.26.3.1‑1 describes the request body and possible responses.

Table 6.26.3.1-1: Retrieve Available Entity Type request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityTypeInfo	1	200 OK	A response body containing the JSON-LD representation of the detailed information about the available entity type.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an entity type not known to the system, see clause 6.3.2.

6.27 Resource: attributes/

6.27.1 Description

This resource represents the attributes available in an NGSI-LD system.

6.27.2 Resource definition

Resource URI:

/attributes/

6.27.3 Resource methods

6.27.3.1 GET

This method is associated to the operations "Retrieve Available Attributes" and "Retrieve Details of Available Attributes" (if the details parameter is set to true) and shall exhibit the behaviour defined by clauses 5.7.8 and 5.7.9 respectively.

Figure 6.27.3.1-1: Retrieve Available Attributes interaction

The request parameters that shall be supported are those defined in Table 6.27.3.1‑1 and Table 6.27.3.1‑2 describes the request body and possible responses.

Table 6.27.3.1-1: Retrieve Available Attributes: optional parameter

Name	Data Type	Cardinality	Remarks
details	Boolean	0..1	If true, then detailed attribute information represented as an array with elements of the Attribute data structure (clause 5.2.28) is to be returned

Table 6.27.3.1-2: Retrieve Available Attributes request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	AttributeList	1	200 OK	A response body containing the JSON-LD representation of the AttributeList (clause 5.2.27) is to be returned, unless details=true is specified.
	Attribute[]	1	200 OK	If details=true is specified, a response body containing a JSON-LD array with elements of the Attribute data structure (clause 5.2.28) is to be returned.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.28 Resource: attributes/{attrId}

6.28.1 Description

This resource represents the specified attribute that belongs to entity instances existing within the NGSI-LD system.

6.28.2 Resource definition

Resource URI:

/attributes/{attrId}

Resource URI variables for this resource are defined in Table 6.28.2‑1.

Table 6.28.2-1: URI variables

Name	Definition
attrId	Name of the attribute for which detailed information is to be retrieved. The Fully Qualified Name (FQN) as well as the short name can be used, given that the latter is part of the JSON-LD @context provided.

6.28.3 Resource methods

6.28.3.1 GET

This method is associated to the operation "Retrieve Available Attribute Information" and shall exhibit the behaviour defined by clause 5.7.10. The attribute is the value of the resource URI variable "attrId". Figure 6.28.3.1‑1 shows the retrieve available attribute information interaction.

Figure 6.28.3.1-1: Retrieve Available Attribute Information interaction

Table 6.28.3.1‑1 describes the request body and possible responses.

Table 6.28.3.1-1: Retrieve Available Attribute Information request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Attribute	1	200 OK	A response body containing the JSON-LD representation of the detailed information about the available attribute.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an attribute name not known to the system, see clause 6.3.2.

6.29 Resource: jsonldContexts/

6.29.1 Description

This resource represents the @contexts known to an NGSI-LD system.

6.29.2 Resource definition

Resource URI:

/jsonldContexts/

6.29.3 Resource methods

6.29.3.1 POST

This method is bound to the operation "Add @context" and shall exhibit the behaviour defined by clause 5.13.2, taking the @context to be added from the HTTP request payload body. Figure 6.29.3.1‑1 shows the Add @context interaction and Table 6.29.3.1‑1 describes the request body and possible responses.

Figure 6.29.3.1-1: Add @context interaction

Table 6.29.3.1-1: Add @context request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	JSON Object	1	Payload body in the request contains a JSON object that has a root node named @context, which represents a JSON-LD "local context".
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	201 Created	The HTTP response shall include a "Location" HTTP header that contains the local URI of the added @context.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.29.3.2 GET

This method is associated to the operation "List @contexts" and shall exhibit the behaviour defined by clause 5.13.3, and it provides information about stored @contexts as part of the HTTP response payload body. Figure 6.29.3.2‑1 shows the List @contexts interaction.

Figure 6.29.3.2-1: List @contexts interaction

The request parameters that shall be supported by implementations are those defined in Table 6.29.3.2‑1 and Table 6.29.3.2‑2 describes the request body and possible responses.

Table 6.29.3.2-1: List @contexts request parameters

Name	Data Type	Cardinality	Remarks
details	Boolean	0..1	Whether a list of URLs or a more detailed list of JSON Objects is requested
kind	String	0..1	Can be either "Cached", "Hosted", or "ImplicitlyCreated"

Table 6.29.3.2-2: List @contexts request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	String[] or JSON Object[]	1	200 OK	A response body containing a list of URLs or a list of JSON Objects, as defined in clause 5.13.3.5, representing metadata about stored @contexts.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.30 Resource: jsonldContexts/{contextId}

6.30.1 Description

This resource represents a JSON-LD @context stored in the broker's internal @context storage.

6.30.2 Resource definition

Resource URI:

/jsonldContexts/{contextId}

Resource URI variables for this resource are defined in Table 6.30.2‑1.

Table 6.30.2-1: URI variables

Name	Definition
contextId	Local identifier of the @context to be managed (served or deleted). For @contexts of kind "Cached" this can also be the original URL the broker downloaded the @context from.

6.30.3 Resource methods

6.30.3.1 GET

This method is associated to the operation "Serve @context" and shall exhibit the behaviour defined by clause 5.13.4. The @context identifier is the value of the resource URI variable "contextId". Figure 6.30.3.1‑1 shows the HTTP Serve @context interaction.

Figure 6.30.3.1-1: Serve @context interaction

The request parameters that shall be supported by implementations are those defined in Table 6.30.3.1‑1 and Table 6.30.3.1‑2 describes the request body and possible responses.

Table 6.30.3.1-1: Serve @contexts request parameters

Name	Data Type	Cardinality	Remarks
details	Boolean	0..1	Whether the content of the @context or its metadata is requested

Table 6.30.3.1-2: Serve @context request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	JSON Object	1	200 OK	If the parameter details is false or missing, response body contains a JSON object that has a root node named @context, which represents a JSON-LD "local context". If the parameter details is true, response body contains a JSON object as defined in clause 5.13.4.5, which metadata of a JSON-LD "local context".
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an @context identifier not known to the system, see clause 6.3.2.
	ProblemDetails (see IETF RFC 7807 [10])	1	422 Unprocessable	It is used when a client indicated an @context of type "Cached", see clause 6.3.2.

6.30.3.2 DELETE

This method is associated to the operation "Delete and Reload @context" and shall exhibit the behaviour defined by clause 5.13.5. The Entity identifier is the value of the resource URI variable "contextId". Figure 6.30.3.2‑1 shows the delete entity interaction. The request parameters that shall be supported are those defined in Table 6.30.3.2‑1 and Table 6.30.3.2‑2 describes the request body and possible responses.

Table 6.30.3.2-1: Delete and Reload @context request parameters

Name	Data Type	Cardinality	Remarks
reload	Boolean	0..1	indicates to perform a download and replace of the @context, as specified in clause 5.13.5.4.

Figure 6.30.3.2-1: Delete and Reload @context interaction

Table 6.30.3.2-2: Delete and Reload @context request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an @context identifier not known to the system, see clause 6.3.2.
	ProblemDetails (see IETF RFC 7807 [10])	1	504 Gateway Timeout	It is used when re-downloading fails.

6.31 Resource: entityOperations/merge

6.31.1 Description

A sub-resource, pertaining to the entityOperations/ resource, intended to enable batch entity merge for the NGSI-LD API.

6.31.2 Resource definition

Resource URI:

/entityOperations/merge

6.31.3 Resource methods

6.31.3.1 POST

This method is associated to the operation "Batch Entity Merge" and shall exhibit the behaviour defined by clause 5.6.20. Figure 6.31.3.1‑1 shows the operation interaction and Table 6.31.3.1‑1 describes the request body and possible responses.

Figure 6.31.3.1-1: Batch Entity Merge Interaction

Table 6.31.3.1-1: Batch Entity Merge Interaction and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Entity[]	1	Array of Entities to be merged.
Response Body	Data Type	Cardinality	Response Code	Remarks
	N/A	N/A	204 No Content	If all entities have been successfully merged, there is no payload body in the response.
	BatchOperationResult	1	207 Multi-Status	If only some or none of the entities have been successfully merged, a response body containing the result of each operation contained in the batch is returned in a BatchOperationResult structure. It contains two arrays. The first array (success) contains the URIs of the successfully merged entities, while the second array (errors) contains information about the error for each of the entities that could not be merged-patched. There is no restriction as to the order of the Entity IDs in the arrays. If any of the entities matches to a registration, the relevant parts of the request are forwarded as a distributed operation. In the case when an error response is received back from any distributed operation, a response body containing the result returned from each registration is returned in a BatchOperationResult structure. Errors can occur whenever a distributed operation is unsupported, fails or times out, see clause 6.3.17.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.32 Resource: entityMaps/{entityMapId}

6.32.1 Description

This resource represents an EntityMap available in the broker's internal storage or memory.

6.32.2 Resource definition

Resource URI:

/entityMaps/{entityMapId}

Resource URI variables for this resource are defined in Table 6.32.2‑1.

Table 6.32.2-1: URI variables

Name	Definition
entityMapId	Id (URI) of the EntityMap to be retrieved, updated or deleted.

6.32.3 Resource methods

6.32.3.1 GET

This method is associated to the operation "Retrieve EntityMap" and shall exhibit the behaviour defined by clause 5.14.1. The EntityMap identifier is the value of the resource URI variable "entityMapId". Figure 6.32.3.1‑1 shows the Retrieve EntityMap interaction and Table 6.32.3.1‑1 describes the request body and possible responses.

Figure 6.32.3.1-1: Retrieve EntityMap

Table 6.32.3.1-1: Retrieve EntityMap request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityMap	1	200 OK	A response body containing the JSON-LD representation of the target entity.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

6.32.3.2 PATCH

This method is associated to the operation "Update EntityMap" and shall exhibit the behaviour defined by clause 5.14.2. The EntityMap identifier is the value of the resource URI variable "entityMapId". Figure 6.32.3.2‑1 shows the Update EntityMap interaction and Table 6.32.3.2‑1 describes the request body and possible responses.

Figure 6.32.3.2-1: Update EntityMap

Table 6.32.3.2-1: Update EntityMap request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	EntityMap Fragment	1	Payload body in the request contains a JSON-LD object which represents the EntityMap fragment with which the EntityMap is to be updated.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

6.32.3.3 DELETE

This method is associated to the operation "Delete EntityMap" and shall exhibit the behaviour defined by clause 5.14.3. The Entity identifier is the value of the resource URI variable "contextId". Figure 6.32.3.3‑1 shows the delete entity interaction and Table 6.32.3.3‑1 describes the request body and possible responses.

Figure 6.32.3.3-1: Delete and Reload @context interaction

Table 6.32.3.3-1: Delete EntityMap request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	404 Not Found	It is used when a client provided an @context identifier not known to the system, see clause 6.3.2.

6.33 Resource: info/sourceIdentity

6.33.1 Description

This resource represents identity information about the Context Source itself.

6.33.2 Resource definition

Resource URI:

/info/sourceIdentity

6.33.3 Resource methods

6.33.3.1 GET

This method is associated to the operation "Retrieve Context Source Identity Information" and shall exhibit the behaviour defined by clause 5.15.1. Figure 6.33.3.1‑1 shows the Retrieve Context Source Identity Information interaction and Table 6.33.3.1‑1 describes the request body and possible responses.

Figure 6.33.3.1-1: Retrieve Context Source Identity Information

Table 6.33.3.1-1: Retrieve Context Source Identity Information request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	ContextSourceIdentity	1	200 No Content	A response body containing the JSON-LD representation of the Context Source Identity Information.
	ProblemDetails (see IETF RFC 7807 [10])	1	501 Not Implemented	It is used by Context Sources to indicate that retrieval of the Context Source information is unsupported see .

6.34 Resource: entityMaps

6.34.1 Description

This resource represents the Entity maps in an NGSI-LD system.

6.34.2 Resource definition

Resource URI:

/entityMaps/

6.34.3 Resource methods

6.34.3.1 GET

This method is associated to the operation "Create EntityMap for Query Entities" and shall exhibit the behaviour defined by clause 5.14.4, providing an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Create EntityMap for Query Entities " operations via POST is defined in clause 6.34.3.2. Figure 6.34.3.1‑1 shows the Create EntityMap for Query Entities interaction.

Figure 6.34.3.1‑1: Create EntityMap for Query Entities interaction

The query parameters that shall be supported by implementations are the same as those for Query Entities and can be found in Table 6.4.3.2‑1. Table 6.34.3.1‑1 describes the request body and possible responses.

Table 6.34.3.1‑1: Create EntityMap for Query Entities request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityMap	1	201 Created	A response body containing the entityMap with the identifiers of the Entities matching the query. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	EntityMap	1	203 Non-Authoritative Information	As above, but returning an altered response body, amended to conform to a specific version of the NGSI-LD specification as mandated in clause 4.3.6.8. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.
	ProblemDetails (see IETF RFC 7807 [10])	1	501 Not Implemented	It is used by Registered Context Sources to indicate that the data format of the request is unsupported see clause 6.3.7.

6.34.3.2 POST

This method is associated to the operation "Create EntityMap for Query Entities" and shall exhibit the behaviour defined by clause 5.14.4. Figure 6.34.3.2‑1 shows the operation interaction and Table 6.34.3.2‑1 describes the request body and possible responses.

Figure 6.34.3.2-1: Create EntityMap for Query Entities via POST Interaction

Table 6.34.3.2-1: Create EntityMap for Query Entities via POST Interaction request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Query	1	Payload body in the request contains a JSON-LD object which represents the query to be performed.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityMap	1	201 Created	A response body containing the entityMap with the identifiers of the Entities matching the query. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.35 Resource: temporal/entityMaps

6.35.1 Description

This resource is used for creating entityMaps based on temporal queries in an NGSI-LD system.

6.35.2 Resource definition

Resource URI:

/temporal/entityMaps/

6.35.3 Resource methods

6.35.3.1 GET

This method is associated to the operation "Create EntityMap for Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by clause 5.14.5, an EntityMap as part of the HTTP response payload body. In addition to this method, an alternative way to perform "Create EntityMap for Query Temporal Evolution of Entities" operations via POST is defined in clause 6.35.3.2. Figure 6.35.3.1‑1 shows this interaction.

Figure 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities interaction

The query parameters that shall be supported by implementations are the same as those for Query Temporal Evolution of Entities and can be found in Table 6.18.3.2‑1. Table 6.35.3.1‑1 describes the request body and possible responses.

Table 6.35.3.1-1: Create EntityMap for Query Temporal Evolution of Entities request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityMap	1	201 Created	A response body containing the entityMap with the identifiers of the Entities matching the query. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

6.35.3.2 POST

This method is associated to the operation "Create EntityMap for Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by clause 5.14.5. Figure 6.35.3.2‑1 shows the operation interaction and Table 6.35.3.2‑1 describes the request body and possible responses.

Figure 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST Interaction

Table 6.35.3.2-1: Create EntityMap for Query Temporal Evolution of Entities via POST Interaction request body and possible responses

Request Body	Data Type	Cardinality	Remarks
Request Body	Query	1	Payload body in the request contains a JSON-LD object which represents the query to be performed.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	EntityMap	1	201 Created	A response body containing the entityMap with the identifiers of the Entities matching the query. The HTTP response shall include an "NGSILD-EntityMap" HTTP header that contains the resource URI of the EntityMap resource created in the operation.
	ProblemDetails (see IETF RFC 7807 [10])	1	400 Bad Request	It is used to indicate that the request or its content is incorrect, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.