Intellectual Property Rights

IPRs essential or potentially essential to normative deliverables may have been declared to ETSI. The declarations pertaining to these essential IPRs, if any, are publicly available for ETSI members and non-members, and can be found in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI IPR online database.

Pursuant to the ETSI Directives including the ETSI IPR Policy, no investigation regarding the essentiality of IPRs, including IPR searches, has been carried out by ETSI. No guarantee can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web server) which are, or may be, or may become, essential to the present document.

The present document may include trademarks and/or tradenames which are asserted and/or registered by their owners. ETSI claims no ownership of these except for any which are indicated as being the property of ETSI, and conveys no right to use or reproduce any trademark and/or tradename. Mention of those trademarks in the present document does not constitute an endorsement by ETSI of products, services or organizations associated with those trademarks.

DECT™, PLUGTESTS™, UMTS™ and the ETSI logo are trademarks of ETSI registered for the benefit of its Members. 3GPP™, LTE™ and 5G™ logo are trademarks of ETSI registered for the benefit of its Members and of the 3GPP Organizational Partners. oneM2M™ logo is a trademark of ETSI registered for the benefit of its Members and of the oneM2M Partners. GSM^® and the GSM logo are trademarks registered and owned by the GSM Association.

Foreword

This Technical Specification (TS) has been produced by ETSI Technical Committee Data Solutions (TC DATA).

Modal verbs terminology

In the present document "should", "should not", "may", "need not", "will", "will not", "can" and "cannot" are to be interpreted as described in clause 3.2 of the ETSI Drafting Rules (Verbal forms for the expression of provisions).

"must" and "must not" are NOT allowed in ETSI deliverables except when used in direct citation.

Executive summary

The core abstract NGSI-LD API [1] is conceived as independent of any particular binding between the operations of the API and the specific protocols implementing them. The present document defines a binding of the API operations to the HTTP protocol.

Introduction

The present document defines the HTTP binding of the NGSI-LD API.

The NGSI-LD API [1] and information model benefited from contributions developed in the context of the following research projects:

• No. 101136799 (MARCLAIMED)
• No. 101180452 (URBAQUANTUM)
• No. 101270878 (DYNACITY)
• No. 101081802 (CONSERWA)
• No. G69J18001180007 (Data Highway)
• No. FTE0000471 (GeminiPort)
• No. PE00000001 (DUSTAR, RESTART SPOKE 6)
• No. 101069732 (aerOS)
• No. 101135784 (ARISE)
• No. 101189589 (O-CEI)

and from contributions developed by members of the FIWARE^® Community.

1 Scope

The present document defines the HTTP binding for the NGSI-LD API specified in ETSI TS 104 175 [1]. It supersedes prior versions, including ETSI GS CIM 009 [i.1] and ETSI GS CIM 004 [i.2].

2 References

2.1 Normative references

References are either specific (identified by date of publication and/or edition number or version number) or non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.

Referenced documents which are not found to be publicly available in the expected location might be found in the ETSI docbox.

The following referenced documents are necessary for the application of the present document.

2.2 Informative references

References are either specific (identified by date of publication and/or edition number or version number) or non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the referenced document (including any amendments) applies.

The following referenced documents may be useful in implementing an ETSI deliverable or add to the reader's understanding, but are not required for conformance to the present document.

3 Definition of terms, symbols and abbreviations

3.1 Terms

For the purposes of the present document, the following terms apply:

NGSI-LD Attribute: reference to both an NGSI-LD Property and to an NGSI-LD Relationship

NGSI-LD Attribute Instance (in case of temporal representation of NGSI-LD Entities): reference to an NGSI-LD Attribute, at a specific moment in time of its temporal evolution, usually identified by its instanceId

NGSI-LD Central Broker: NGSI-LD Context Broker that only uses a local storage when serving NGSI-LD requests, without involving any external Context Sources

NGSI-LD Context Broker: architectural component that implements all the NGSI-LD interfaces

NGSI-LD Context Consumer: agent that uses the query and subscription functionality of NGSI-LD to retrieve context information

NGSI-LD Context Producer: agent that uses the NGSI-LD context provision and/or registration functionality to provide or announce the availability of its context information to an NGSI-LD Context Broker

NGSI-LD Context Registry: software functional element where Context Sources register the information that they can provide

NGSI-LD Context Source: source of context information which implements the NGSI-LD consumption and subscription (and possibly provision) interfaces defined by the present document

NGSI-LD Context Source Registration: description of the information that can be provided by a Context Source, which is used when registering the Context Source with the Context Registry

NGSI-LD Core API: core part of the NGSI-LD API that has to be implemented by all Brokers, including operations for providing or managing Entities and Attributes, operations for consuming Entities and checking which Entity Types and Attributes Entities are available in the system and operations for subscribing to Entities, receiving notifications and managing subscriptions

NGSI-LD Distribution Broker: NGSI-LD Context Broker that uses both local context information and registration information from an NGSI-LD Context Registry, to access matching context information from a set of distributed Context Sources

NGSI-LD Element: any JSON element that is defined by the NGSI-LD API

NGSI-LD Entity: informational representative of something that is supposed to exist in the real world, physically or conceptually

NGSI-LD Entity Map: mapping of NGSI-LD Entity ids to Context Source Registrations used in maintaining atomicity of transactions performed by Distribution Brokers and Federation Brokers

NGSI-LD Entity Type: categorization of an NGSI-LD Entity as belonging to a class of similar entities, or sharing a set of characteristic properties

NGSI-LD External Linked Entity: Linked Entity that is identified through a dereferenceable URI which does not exist within the current NGSI-LD system

NGSI-LD Federation Broker: Distribution Broker that federates information from multiple underlying NGSI-LD Context Brokers and across domains

NGSI-LD GeoProperty: subclass of NGSI-LD Property which is a description instance which associates a main characteristic, i.e. an NGSI-LD Value, to either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property, that uses the special hasValue property to define its target value and holds a geographic location in GeoJSON format

NGSI-LD Internal Linked Entity: Linked Entity that exists within the current NGSI-LD system

NGSI-LD JSONLDContext API: part of the NGSI-LD API that is used to host, serve and manage JSON-LD @contexts

NGSI-LD JsonProperty: subclass of NGSI-LD Property which is a description instance which associates a raw JSON literal value as a defined main characteristic to an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasJson (a subproperty of hasValue) property to define its target value

NGSI-LD LanguageProperty: subclass of NGSI-LD Property which is a description instance which associates a set of strings in different natural languages as a defined main characteristic, i.e. an NGSI-LD Map, to an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasLanguageMap (a subproperty of hasValue) property to define its target value

NGSI-LD Linked Entity: NGSI-LD Entity referenced from another NGSI-LD Entity (the linking NGSI-LD Entity) via an NGSI-LD Relationship

NGSI-LD Linking Entity: NGSI-LD Entity which is the subject of a Relationship to another NGSI-LD Entity (the linked NGSI-LD Entity) or an external resource (identified by a URI)

NGSI-LD ListProperty: description instance which associates an ordered array of main characteristics, i.e. NGSI-LD Values, to either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasValueList property to define its target value

NGSI-LD ListRelationship: description of an ordered array of directed links between a subject which is either an NGSI-LD Entity, an NGSI-LD Property or another NGSI-LD Relationship on one hand, and a series of objects, which are NGSI-LD Entities, on the other hand, and which uses the special hasObjectList property to define its target objects

NGSI-LD Map: JSON-LD language map in the form of key-value pairs holding the string representation of a main characteristic in a series of natural languages

NGSI-LD Null: "urn:ngsi-ld:null" or {"@none": "urn:ngsi-ld:null"} used as an encoding for null values

NGSI-LD Property: description instance which associates a main characteristic, i.e. an NGSI-LD Value, to either an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasValue property to define its target value

NGSI-LD Query: collection of criteria used to select a sub-set of NGSI-LD Elements, matching the criteria

NGSI-LD Registry API: part of the NGSI-LD API that is implemented by the Context Registry, including operations for registering Context Sources and managing Context Source Registrations (CSRs), operations for retrieving and discovering CSRs, and operations for subscribing to CSRs and receiving notifications

NGSI-LD Relationship: description of a directed link between a subject which is either an NGSI-LD Entity, an NGSI-LD Property or another NGSI-LD Relationship on one hand, and an object, or unordered array of objects, each of which is an NGSI-LD Entity, on the other hand, and which uses the special hasObject property to define its target object

NGSI-LD Scope: hierarchical structuring of Entities that enables restricting query results and notifications

NGSI-LD Snapshot: set of NGSI-LD Entities, retrieved through one or more NGSI-LD Queries, which are locally persisted, providing a relatively consistent view of the situation when the queries were executed, and on which Context Consumers can execute further local NGSI-LD Operations

NGSI-LD Temporal API: part of the NGSI-LD API pertaining to the Temporal Evolution of Entities, including operations for providing and managing the Temporal Evolution of Entities and Attributes, and operations for consuming the Temporal Evolution of Entities

NGSI-LD Temporal Evolution of an Entity: sequence of values attributed to an NGSI-LD Entity over time, i.e. its history or future predictions

NGSI-LD Tenant: user or group of users that utilize a single instance of a system implementing the NGSI-LD API (NGSI-LD Context Source or NGSI-LD Broker) in isolation from other users or groups of users of the same instance, so that any information related to one Tenant (e.g. Entities, Subscriptions, Context Source Registrations) are only visible to users of the same Tenant, but not to users of a different Tenant

NGSI-LD Value: JSON value (i.e. a string, a number, true or false, an object, an array), or JSON-LD typed value (i.e. a string as the lexical form of the value together with a type, defined by an XSD base type or more generally an IRI), or JSON-LD structured value (i.e. a set, a list, a language-tagged string)

NGSI-LD VocabProperty: subclass of NGSI-LD Property which is a description instance which associates a string value which can be coerced to a URI as a defined main characteristic to an NGSI-LD Entity, an NGSI-LD Relationship or another NGSI-LD Property and that uses the special hasVocab (a subproperty of hasValue) property to define its target value

3.2 Symbols

Void.

3.3 Abbreviations

For the purposes of the present document, the following abbreviations apply:

4 Introduction

The present document defines the HTTP binding of the NGSI-LD API, whose abstract operations are defined in ETSI TS 104 175 [1]. In particular it defines the mapping of the abstract operations of the NGSI-LD API to HTTP resources and verbs. Each HTTP resource is defined IETF RFC 9110 [2] IETF RFC 7232 [3], which verbs are applicable and what the related request and response payload bodies are.

In the present document, a number of rather obvious typographic conventions and syntax guidelines are followed, and the reader is referred to Annex B for details.

A non-normative OpenAPI™ Specification [i.5] of the referred HTTP binding can be found in NGSI-LD OpenAPI™ Specification [i.6].

5 Global definitions and resource structure

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

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

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 [4]). TLS version 1.2 as defined by IETF RFC 5246 [5] 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 5-1 and methods defined on them are shown in Table 5-1.

An OpenAPI companion specification is available, see ETSI GS CIM 047 [6].

Resource Name	Resource URI	HTTP Method	Meaning	Clauses
Entity List	/entities/	GET / HEAD	Query entities	10.4.3*; 7.2.3.1
		POST	Entity creation	10.2.2*; 7.2.3.2
		DELETE	Purge entities	10.2.12*; 7.2.3.3
Entity by id	/entities/{entityId}	GET / HEAD	Entity retrieval by id	10.4.2*; 7.3.3.1
		PATCH	Entity merge by id	10.2.9*; 7.3.3.2
		PUT	Entity replacement by id	10.2.10*; 7.3.3.3
		DELETE	Entity deletion by id	10.2.8*; 7.3.3.4
Attribute List	/entities/{entityId}/attrs/	POST	Append Attributes to Entity	10.2.4*; 7.4.3.1
		PATCH	Update Attributes of an Entity	10.2.3*; 7.4.3.2
Attribute by id	/entities/{entityId}/attrs/{attrId}	PATCH	Partial Attribute update	10.2.5*; 7.5.3.2
		PUT	Attribute replacement	10.2.11*; 7.5.3.3
		DELETE	Attribute deletion	10.2.7*; 7.5.3.4
Attribute Value	/entities/{entityId}/attrs/{attrId}/value	GET/HEAD	Retrieve Attribute Value	10.4.4*; 7.6.3.1
		PUT	Set Attribute Value	10.2.6*; 7.6.3.2
Subscriptions List	/subscriptions/	GET/HEAD	Retrieve list of Subscriptions	10.5.5*; 7.13.3.1
		POST	Create Subscription	10.5.2*; 7.13.3.2
Subscription by Id	/subscriptions/{subscriptionId}	GET / HEAD	Subscription retrieval by id	10.5.4*; 7.14.3.1
		PATCH	Subscription update by id	10.5.3*; 7.14.3.2
		DELETE	Subscription deletion by id	10.5.6*; 7.14.3.3
Entity Types	/types/	GET / HEAD	Retrieve available entity types	10.6.3* and 10.6.4*; 7.15.3.1
Entity Type	/types/{type}	GET / HEAD	Details about available entity type	10.6.5*; 7.16.3.1
Attributes	/attributes/	GET / HEAD	Available attributes	10.6.6* and 10.6.7*; 7.17.3.1
Attribute	/attributes/{attrId}	GET / HEAD	Details about available attribute	10.6.8*; 7.18.3.1
Context source registration list	/csourceRegistrations/	GET /HEAD	Discover Csource registrations	12.3.3*; 9.2.3.1
		POST	Csource registration creation	12.2.2*; 9.2.3.2
Context source registration by Id	/csourceRegistrations/{registrationId}	GET / HEAD	Csource registration retrieval by id	12.3.2*; 9.3.3.1
		PATCH	Csource registration update by id	12.2.3*; 9.3.3.2
		DELETE	Csource registration deletion by id	12.2.4*; 9.3.3.3
Context source registration subscription list	/csourceSubscriptions/	GET / HEAD	Retrieval of list of subscription to Csource registration	12.4.5*; 9.4.3.1
		POST	Create subscription to Csource registration	12.4.2*; 9.4.3.2
Context source registration subscription by Id	/csourceSubscriptions/{subscriptionId}	GET / HEAD	Csource registration subscription retrieval by id	12.4.4*; 9.5.3.1
		PATCH	Csource registration subscription update by id	12.4.3*; 9.5.3.2
		DELETE	Csource registration subscription deletion by id	12.4.6*; 9.5.3.3
Entity Operations. Create	/entityOperations/create	POST	Batch Entity creation	10.3.2*; 7.7.3.1
Entity Operations. Upsert	/entityOperations/upsert	POST	Batch Entity creation or update (upsert)	10.3.3*; 7.8.3.1
Entity Operations. Update	/entityOperations/update	POST	Batch Entity update	10.3.4*; 7.9.3.1
Entity Operations. Delete	/entityOperations/delete	POST	Batch Entity deletion	10.3.6*; 7.11.3.1
Entity Operations. Query	/entityOperations/query	POST	Query entities based on POST	10.4.3*; 7.12.3.1
Entity Operations. Merge	/entityOperations/merge	POST	Batch Entity merge	10.3.5*; 7.10.3.1
Temporal Evolution of Entities	/temporal/entities/	GET / HEAD	Query Temporal Evolution of Entities	11.3.3*; 8.2.3.1
		POST	Temporal Evolution of an Entity creation	11.2.2*; 8.2.3.2
Temporal Evolution of an Entity by id	/temporal/entities/{entityId}	GET / HEAD	Temporal Evolution of an Entity retrieval by id	11.3.2*; 8.3.3.1
		DELETE	Temporal Evolution of an Entity deletion by id	11.2.7*; 8.3.3.1
Temporal Representation of Attribute List	/temporal/entities/{entityId}/attrs	POST	Temporal Evolution of Attribute of an Entity instance addition	11.2.3*; 8.4.3.1
Temporal Representation of Attribute by id	/temporal/entities/{entityId}/ attrs/{attrId}	DELETE	Attribute from Temporal Evolution of an Entity deletion	11.2.4*; 8.5.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	11.2.5*; 8.6.3.1
		DELETE	Attribute Instance from Temporal Evolution of an Entity deletion by instance id	11.2.6*; 8.6.3.2
Create EntityMap for Query Temporal Evolution of Entities	/temporal/entityMaps	GET / HEAD	Query temporal evolution of entities for creating entity map	14.6*; 11.3.3.1
		POST	Query temporal evolution of entities for creating entity map based on POST	14.6*; 11.3.3.2
Temporal Query Operation	/temporal/entityOperations/query	POST	Query Temporal Evolution of Entities based on POST	11.3.3*; 7.12.3.1
Add and List @context	/jsonldContexts/	GET / HEAD	List all cached @contexts	13.3*; 10.2.3.1
		POST	Add a user @context to the internal cache	13.2*; 10.2.3.2
Serve, Delete and Reload @context	/jsonldContexts/{contextId}	GET / HEAD	Serve one specific user @context	13.4*; 10.3.3.1
		DELETE	Delete one specific @context from internal cache, possibly re-inserting a freshly downloaded copy of it	13.5*; 10.3.3.2
Create EntityMap for Query Entities	/entityMaps/	GET / HEAD	Query entities for creating entity map	14.5*; 11.2.3.1
		POST	Query entities for creating entity map based on POST	14.5*; 11.2.3.2
Retrieve, Update and Delete Entity Maps	/entityMaps/{entityMapId}	GET / HEAD	EntityMap Retrieval by id	14.2*; 11.4.3.1
		PATCH	EntityMap Update by id	14.3*; 11.4.3.2
		DELETE	EntityMap Deletion by id	14.4*; 11.4.3.3
Retrieve Context Source Identity Information	/info/sourceIdentity	GET / HEAD	Context Source Identity Retrieval	15.2*; 12.2.3.1
Create Snapshot or Purge Snapshots	/snapshots/	POST	Create Snapshot	16.2*; 13.2.3.1
		DELETE	Purge Snapshots	16.7*; 13.2.3.2
Retrieve and Update Snapshot Status or Delete Snapshot	/snapshots/{snapshotId}	GET / HEAD	Retrieve Snapshot Status	16.4*; 13.3.3.1
		PATCH	Update Snapshot Status	16.5*; 13.3.3.2
		DELETE	Delete Snapshot	16.6*; 13.3.3.3
Clone Snapshot	/snapshots/{snapshotId}/clone	POST	Clone Snapshot	16.3*; 13.4.3.1
NOTE: In the “Clauses” column, entries marked with an asterisk (*) indicate a reference ETSI TS 104 175 [1].

For every defined resource URI defined above, it shall be possible to retrieve information about the communication options available on that resource using the OPTIONS method. The response being an "Allow" header field in the response containing a list of the target resource's currently supported methods.

Where defined, a HEAD request shall function in the same manner as a GET request, but shall omit the body in the response. The response code 204 No Content shall be used on success.

6 Common behaviours

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 IETF RFC 9110 [2], IETF RFC 7232 [3] verbs, request and response payload bodies.

A non-normative OpenAPI™ Specification [i.5] of the referred HTTP binding can be found at NGSI-LD OpenAPI™ Specification [i.6].

6.2 General mapping to HTTP

6.2.1 Introduction

Context broker implementations are general-purpose servers as defined by IETF RFC 9110 [2], and in this respect all standard HTTP verbs GET, HEAD, POST, PATCH, PUT, DELETE and OPTIONS shall be recognized.

6.2.2 HTTP request preconditions

For HTTP POST, PATCH and PUT 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 [7]. 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 ETSI TS 104 175 [1] clause 10.4.3) and "Query Temporal Evolutions of Entities" (see ETSI TS 104 175 [1] clause 11.3.3), 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 9110 [2], 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 ETSI TS 104 175 [1] clause 10.4.2) and "Query Entity" (ETSI TS 104 175 [1] clause 10.4.3) 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.2.3 HTTP response common requirements

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

• 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 JSON-LD 1.1 [8], section 6.2:

  • If the Prefer header IETF RFC 7240 [9] 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 ETSI TS 104 175 [1] clause 9.5.3.

• 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 IETF RFC 7240 [9] 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 ETSI TS 104 175 [1] clause 9.5.3.
• If the target response's MIME type is "application/geo+json" and the Prefer Header IETF RFC 7240 [9] 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 IETF RFC 7240 [9] is set to "body=json" such response shall include a Link to the associated JSON-LD @context as mandated by JSON-LD 1.1 [8], 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.2.4 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, HEAD or DELETE, then the associated JSON-LD @context shall be obtained from a Link header IETF RFC 8288 [10] as mandated by JSON-LD 1.1 [8], section 6.2. In the absence of such Link header, then the associated @context shall be the default JSON-LD @context.

• 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 1.1 [8], 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, HEAD and DELETE operations always take their input @context from the JSON-LD Link Header.

6.3 Errors and error handling

6.3.1 Introduction

This clause defines error handling and how errors are expressed within the HTTP Binding of the NGSI-LD API.

6.3.2 Error types

This clause associates API error types (which shall be contained in the response payload body) defined by ETSI TS 104 175 [1] clause 8.3.2 with HTTP status codes as shown in Table 6.3.2-1.

Error Type	HTTP status
https://uri.etsi.org/ngsi-ld/errors/AlreadyExists	409
https://uri.etsi.org/ngsi-ld/errors/BadRequestData	400
https://uri.etsi.org/ngsi-ld/errors/InternalError	500
https://uri.etsi.org/ngsi-ld/errors/InvalidRequest	400
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
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/TooComplexQuery	403
https://uri.etsi.org/ngsi-ld/errors/TooManyResults	403

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 recognized but unsupported HTTP verb over a resource. Implementations shall provide the allowed HTTP methods as mandated by IETF RFC 9110 [2] 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".
• "Not Implemented" (501) which shall be raised when a client invokes an HTTP verb that is unrecognized or not implemented. Note that as a general-purpose server, a Context broker shall recognise the methods GET and HEAD on all endpoints.

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.3 depending on error type.
• Payload body: A JSON object including all the terms defined by ETSI TS 104 175 [1] clause 8.3.3.

6.3.4 Expiration time for cached @contexts

Implementations shall comply with the Expires header field (section 5.3 of IETF RFC 7234 [11]) or a max-age or s-maxage response directive of Cache-Control header field (section 5.2.2 of IETF RFC 7234 [11]) 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 [11] section 4.2.2) expiration time when an explicit time is not specified.

6.3.5 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 TTable 6.3.5-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 [12] 110 - Response is Stale.

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

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.. This applies to the case described in ETSI TS 104 175 [1] clause 9.7, when a loop has been detected.
• 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 ETSI TS 104 175 [1] Table 5.2.6.5.3-1) has been reached.

6.3.6 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.4 Mapping NGSI-LD features to URI parameters and HTTP headers

6.4.1 Introduction

This clause defines the common input parameters and HTTP Response Headers required to be able to express data and within the NGSI-LD API.

6.4.2 Representation of Entities

For HTTP GET and POST operations corresponding to "Retrieve Entity" (see ETSI TS 104 175 [1] clause 10.4.2) and "Query Entities" ( see ETSI TS 104 175 [1] clauses 10.4.2 and 10.4.3), Context Broker implementations shall support the parameter specified in Table 6.4.2-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.

Name	Data Type	Cardinality	Remarks
format	String	0..1	When its value is "normalized", a normalized representation of Entities shall be provided as defined in ETSI TS 104 175 [1] clauses 5.3.2.2 and 5.3.3.3. When its value is "concise", a concise lossless representation of Entities shall be provided as defined in ETSI TS 104 175 [1] clauses 5.3.2.3 and 5.3.3.4. 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 in ETSI TS 104 175 [1] clauses 5.3.2.4 and 5.3.3.5. If the Accept Header is set to "application/geo+json" the response will be in GeoJSON format as defined in ETSI TS 104 175 [1] clause 5.3.3.
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 in ETSI TS 104 175 [1] clauses 5.3.2.2 and 5.3.3.3. When its value includes the keyword "concise", a concise lossless representation of Entities shall be provided as defined in ETSI TS 104 175 [1] clauses 5.3.2.3 and 5.3.3.4. 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 in ETSI TS 104 175 [1] clause 5.3.2.4 and 5.3.3.5. If the Accept Header is set to "application/geo+json" the response will be in GeoJSON format as defined as defined in ETSI TS 104 175 [1] clause 5.3.3.

6.4.3 Simplified or aggregated temporal representation of Entities

For HTTP GET and POST operations corresponding to "Retrieve Temporal Evolution of an Entity" (see clause 11.3.2) and "Query Temporal Evolution of Entities" (see clause 11.3.3), implementations shall support the parameter specified in Table 6.4.3-1.

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 ETSI TS 104 175 [1] clause 5.3.2.6. When its value is "aggregatedValues", an aggregated temporal representation of entities shall be provided as defined by ETSI TS 104 175 [1] clause 5.3.2.7.
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 5.3.2.6. When its value includes the keyword "aggregatedValues", an aggregated temporal representation of entities shall be provided as defined by ETSI TS 104 175 [1] clause 5.3.2.7. 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.4.4 GeoJSON representation of spatially bound Entities

For HTTP GET and POST operations corresponding to "Retrieve Entity" (see ETSI TS 104 175 [1] clause 10.4.2) and "Query Entities" (see ETSI TS 104 175 [1] clause 10.4.3), 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 ETSI TS 104 175 [1] clause 5.3.3.

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.

Name	Data Type	Cardinality	Remarks
geometryProperty	String	0..1	If not present, "location" is used.

6.4.5 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" (ETSI TS 104 175 [1] clause 10.4.3) and "Query Temporal Evolutions of Entities" (see ETSI TS 104 175 [1] clause 11.3.3), implementations shall support the parameter specified in Table below. Implementations shall not raise an error if they do not hold system generated temporal attributes.

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.4.6 Counting number of results

This clause implements the behaviour described in ETSI TS 104 175 [1] clause 7.5, in case of HTTP binding.

For HTTP operations corresponding to the operations listed in ETSI TS 104 175 [1] clause 7.4 (see Table 5-1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.4.6-1.

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.4.7 Pagination

6.4.7.1 Introduction

This clause introduces the HTTP binding of NGSI-LD pagination. Clause 6.4.7.2 introduces the general pagination that applies to all NGSI-LD results, whereas clause 6.4.7.3 introduces temporal pagination, a second level of pagination, used in the temporal API to paginate Attribute instances in the Temporal Evolution of Entities.

6.4.7.2 General pagination

For HTTP operations corresponding to the operations listed in ETSI TS 104 175 [1] clause 7.4 (see Table 5-1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in Table 6.4.7.2-1.

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 ETSI TS 104 175 [1] clause 7.4.2.1. 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 ETSI TS 104 175 [1] clause 7.4.2. 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 [10] section 3, as follows:

• The pointers to the next and previous pages (when needed as mandated by ETSI TS 104 175 [1] clause 7.4.2) 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 [13].
  • 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 [13].
• At least, the "type" Link Target Attribute shall be included by the previously described serialized Link Header, as mandated by IETF RFC 8288 [10] section 3.4, 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).

If the transparent pagination option as described in ETSI TS 104 175 [1] clause 7.2.3 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.4.7.2-1 and the offset parameter as specified in Table 6.4.7.2-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.

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.

6.4.7.3 Temporal pagination

As defined in ETSI TS 104 175 [1] clause 7.4.5, there is an additional temporal dimension to pagination that limits the number of Attribute instances for any Attribute in a response. Implementations shall support the HTTP query parameter specified in Table 6.4.7.3-1.

Name	Data Type	Cardinality	Remarks
firstN	Positive Integer	0..1	Only values greater than 0. Only the first n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to offsetN parameter if specified.
lastN	Positive Integer	0..1	Only values greater than 0. Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to offsetN parameter if specified.

For HTTP requests on Temporal Evolution of Entities, where the parameter firstN is present the pagination shall happen in ascending order, with the limit being the value assigned to firstN or the default maximum limit configured, whichever is smaller. The default maximum limit is implementation specific.

In case the parameter lastN is present, the pagination shall happen in descending order, with the limit being the value assigned to lastN or the maximum limit configured, whichever is smaller.

If neither firstN nor lastN is present, ascending order is assumed with the configured default maximum limit.

Particularly, to flag the existence of pages related to the temporal dimension 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 [10] section 3, as follows:

• The pointers to the next page, i.e. in ascending order of the Attribute timestamps, and previous page, i.e. in descending order of the Attribute timestamps 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 with the respective Attribute instances. In addition, the Link Relation Type shall be equal to "intervalafter", registered under the IANA Registry of Link Relation Types [13].
  • 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 with respective Attribute instances. In addition, the Link Relation Type shall be equal to "intervalbefore", registered under the IANA Registry of Link Relation Types [13].
• At least, the "type" Link Target Attribute shall be included by the previously described serialized Link Header, as mandated by IETF RFC 8288 [10] section 3.4, 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).

If the transparent pagination option as described in ETSI TS 104 175 [1] clause 7.2.3 is used, the URI-references for the "intervalafter" and "intervalbefore" link to the next and previous pages respectively should include the offsetN parameter as specified in Table 6.4.7.3-2, giving the Context Consumer more control, i.e. to jump to a desired set of Attribute instances in the results using offsetN.

Name	Data Type	Cardinality	Remarks
offsetN	Integer	0..1	Only values greater or equal to 0. It defines the offset of the Attribute instance that shall be retrieved from the beginning or end of the result set depending on whether the retrieval is in ascending or descending order. If offsetN is set to a value larger than the result set, the offsetN 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.

6.4.8 Tenant specification

If the system implementing the NGSI-LD API supports multi-tenancy as described in ETSI TS 104 175 [1] clause 7.8, 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.5.2).

6.4.9 Snapshot specification

If the system implementing the NGSI-LD API supports Snapshots as described in ETSI TS 104 175 [1] clause 7.9, the Snapshot, to which the NGSI-LD HTTP operation is targeted, is specified as the HTTP header "NGSILD-Snapshot", whose value is the identifier of the Snapshot. If the HTTP header "NGSILD-Snapshot" 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-Snapshot" HTTP header (clause 6.5.2).

6.4.10 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 [14], 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 ETSI TS 104 175 [1] clause 8.2.3) through amending the payload body and applying the fallbacks defined within ETSI TS 104 175 [1] clause 9.5.3.

6.4.11 Limiting distributed operations

The parameter described in this clause limits the execution of an operation to a local Context Source or Context Broker (ETSI TS 104 175 [1] clause 8.6). It amends the matching Context Source Registrations behaviour as described in ETSI TS 104 175 [1] clause 9.4, in the case of the HTTP binding in order to avoid cascading distributed operations (see ETSI TS 104 175 [1] clause 9.7). 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.4.11-1. The Registry API operations are always local and thus are not included here. Operations on a Snapshot (see ETSI TS 104 175 [1] clause 7.9) are always implicitly local scope, overriding setting the local parameter to false, i.e. such a setting is to be ignored by implementations.

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 ETSI TS 104 175 [1] clause 9.7).

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 [15]) as specified in Table 6.4.11-2. Any Context 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 ETSI TS 104 175 [1] clause 5.2.6.5.6) as the pseudonym.

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

6.5 Common operation behaviours

6.5.1 Introduction

This clause defines operational behaviour within the HTTP Binding of the NGSI-LD API.

6.5.2 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 ETSI TS 104 175 [1] clauses 5.2.6.5.2, 5.2.6.7.3, 5.2.6.7.4 and 5.2.6.6.1). 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 JSON-LD 1.1 [8], section 6.2 (to the default JSON-LD @context if none available).

If the optional array (of KeyValuePair type, as defined by ETSI TS 104 175 [1] clause 5.2.6.6.3) 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 [15] 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 JSON-LD 1.1 [8], 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.5.3 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 ETSI TS 104 175 [1] clause 5.2.6.5). 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 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 JSON-LD 1.1 [8], section 6.2 (to the default JSON-LD @context if none available).

If the optional array (of KeyValuePair type, as defined by ETSI TS 104 175 [1] clause 5.2.6.6.3 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 [15] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing definitions concerning HTTP headers.

6.5.4 Extra information to provide when contacting Context Sources

As specified in ETSI TS 104 175 [1] clauses 9.5.1 and 9.5.2, extra information to be provided when contacting a Context Source can be specified in the optional array (of KeyValuePair type, as defined by ETSI TS 104 175 [1] clause 5.2.6.6.3) 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 JSON-LD 1.1 [8], 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 [15] 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.

7 Core API resources

7.1 Introduction

This clause describes the resources that are part of the Core API. Each resource is described in a separate section, which includes:

• A brief description of the resource and its purpose.
• The resource definition, including the URI path and any path parameters.
• The resource methods supported, including the HTTP methods, request parameters, and response formats.

7.2 Resource: entities/

7.2.1 Description

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

7.2.2 Resource definition

Resource URI:

• /entities/

7.2.3 Resource methods

7.2.3.1 GET/HEAD

This method is associated to the operation "Query Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.4.3, 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 7.12. Figure 7.2.3.1-1 shows the query entities interaction.

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

Name	Data Type	Cardinality	Remarks
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 ETSI TS 104 175 [1] clause 8.6).	A synonym for a combination of the pick and q members. 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.
collation	String	0..1	An ICU collation (see IETF RFC 6067 [16]), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering.
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.
coordinates	String	0..1 It shall be one if geometry or georel are present.	Coordinates serialized as a string as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
csf	String	0..1	Context Source filter as per ETSI TS 104 175 [1] clause 7.2.3.
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 ETSI TS 104 175 [1] clause 8.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: 2019 [17] format, 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.
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.
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 ETSI TS 104 175 [1] clause 8.6).	Geometry as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
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 top-level geometry field.
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 ETSI TS 104 175 [1] clause 5.2.6.4.5).
georel	String	0..1 It shall be 1 if geometry or coordinates are present.	Geo relationship as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
idPattern	Regular expression as defined by IEEE 1003.2™-1992 [18]	0..1	Regular expression that shall be matched by entity ids.
join	String	0..1	The type of Linked Entity retrieval to apply (see ETSI TS 104 175 [1] clause 7.7). Allowed values: "flat", "inline","@none".
joinLevel	Positive Integer	0..1	Depth of Linked Entity retrieval to apply. Only applicable if join parameter is present.
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.
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.
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.
orderBy	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or an Attribute name) appended with an optional sorting style ("asc", "desc", "dist-asc", "dist-desc") as per ETSI TS 104 175 [1] clause 7.6.2. When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering.
orderFrom	String	0..1 It shall be one if orderBy uses order by distance	Coordinates of a Geometry serialized as a string as per ETSI TS 104 175 [1] clause 7.2.4. It is part of Entity ordering.
orderGeometry	String	0..1	A Geometry type (with the exception of GeometryCollection) as defined by the GeoJSON specification (IETF RFC 7946 [19]). It is part of Entity ordering.
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.
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 ETSI TS 104 175 [1] clause 8.6).	Query as per ETSI TS 104 175 [1] clause 7.2.3.
scopeQ	String	0..1	Scope query (see ETSI TS 104 175 [1] clause 7.2.5).
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.
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 ETSI TS 104 175 [1] clause 8.6).	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2. "*" is also allowed as a value and local is implicitly set to true and shall not be explicitly set to false.

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.

Request Body	Data Type	Cardinality	Remarks
	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 ETSI TS 104 175 [1] clause 9.5.3. 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 [20])	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 [20])	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.4.2.

7.2.3.2 POST

This method is bound to the operation "Create Entity" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.2, taking the entity to be created from the HTTP request payload body. Figure 7.2.3.2-1 shows the Create Entity interaction and Table 7.2.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 relative path of the created entity.
	BatchOperationResult	1	207 Multi-Status	The HTTP response shall include a "Location" HTTP header that contains the relative path of the created entity. 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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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 [20])	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.

7.2.3.3 DELETE

This method is associated to the operation "Purge Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.12, providing entities as part of the HTTP response payload body. Figure 7.2.3.3-1 shows the query entities interaction.

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

Name	Data Type	Cardinality	Remarks
coordinates	String	0..1 It shall be one if geometry or georel are present.	Coordinates serialized as a string as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
csf	String	0..1	Context Source filter as per see ETSI TS 104 175 [1] clause 7.2.3.
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.
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 ETSI TS 104 175 [1] clause 8.6).	Geometry as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
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 top-level geometry field.
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 ETSI TS 104 175 [1] clause 5.2.6.4.5).
georel	String	0..1 It shall be 1 if geometry or coordinates are present.	Geo relationship as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
idPattern	Regular expression as defined by IEEE 1003.2™-1992 [18]	0..1	Regular expression that shall be matched by entity ids.
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 ETSI TS 104 175 [1] clause 8.6).	Query as per ETSI TS 104 175 [1] clause 7.2.3.
scopeQ	String	0..1	Scope query (see ETSI TS 104 175 [1] clause 7.2.5).
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 ETSI TS 104 175 [1] clause 8.6).	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2. "*" is also allowed as a value and local is implicitly set to true and shall not be explicitly set to false.
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.

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.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.3 Resource: entities/{entityId}

7.3.1 Description

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

7.3.2 Resource definition

Resource URI:

• /entities/{entityId}

Resource URI variables for this resource are defined in Table 7.3.2-1.

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

7.3.3 Resource methods

7.3.3.1 GET/HEAD

This method is associated to the operation "Retrieve Entity" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.4.2. The Entity identifier is the value of the resource URI variable "entityId". Figure 7.3.3.1-1 shows the retrieve entity interaction.

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

Name	Data Type	Cardinality	Remarks
attrs	Comma separated list of strings	0..1	A synonym for the pick parameter, except that id, type, scope are not allowed. 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.
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.
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 ETSI TS 104 175 [1] clause 8.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: 2019 [17] format, 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.
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.
join	String	0..1	The type of Linked Entity retrieval to apply (see ETSI TS 104 175 [1] clause 7.7). 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".
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.
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 the Entity (applies to all Entities in the payload in the case of Linked Entity retrieval).
pick	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name). When defined, the Entity is reduced down to only contain the listed Entity members (applies to all Entities in the payload in the case of Linked Entity retrieval).
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

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 retrieval operation is returned in the response.

Request Body	Data Type	Cardinality	Remarks
	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 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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	GeoJSON Feature	1	200 OK 201 Created (in case an EntityMap has been (re)created)	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 [20])	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 [20])	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 [20])	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.4.2.

7.3.3.2 PATCH

This method is bound to the "Merge Entity" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.9. 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 7.3.3.2-1 shows the Merge Entity interaction.

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

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 ETSI TS 104 175 [1] clause 5.3.2.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).
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.
observedAt	String	0..1	It shall be a DateTime (see ETSI TS 104 175 [1] clause 5.2.2.4). 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.
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 ETSI TS 104 175 [1] clause 5.3.2.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 ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2.

7.3.3.3 PUT

This method is bound to the "Replace Entity" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.10. 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 7.3.3.3-1 shows the Replace Entity interaction.

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

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2.

7.3.3.4 DELETE

This method is associated to the operation "Delete Entity" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.8. The Entity identifier is the value of the resource URI variable "entityId". Figure 7.3.3.4-1 shows the delete entity interaction.

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

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.4 Resource: entities/{entityId}/attrs/

7.4.1 Description

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

7.4.2 Resource definition

Resource URI:

• /entities/{entityId}/attrs

Resource URI variables for this resource are defined in Table 7.4.2-1.

Name	Definition
entityId	Id (URI) of the concerned entity

7.4.3 Resource methods

7.4.3.1 POST

This method is bound to the "Append Attributes" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.4. 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 7.4.3.1-1 shows the Append Attributes interaction.

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

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

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.4.3.2 PATCH

This method is bound to the "Update Attributes" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.3. 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 7.4.3.2-1 shows the Update Attributes interaction.

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

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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 ETSI TS 104 175 [1] clause 5.2.6.8.5) 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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an Entity identifier not known to the system, see clause 6.3.2.

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

7.5.1 Description

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

7.5.2 Resource definition

Resource URI:

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

Resource URI variables for this resource are defined in Table 7.5.2-1.

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

7.5.3 Resource methods

7.5.3.1 GET/HEAD

This method is associated to the operation "Retrieve Attribute Value" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.4.4, providing an Attribute Fragment as part of the HTTP response payload body.

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

Name	Data Type	Cardinality
datasetId	String	0..1	Shall be a valid URI, "@none" for return the default Attribute instance. Specifies the datasetId of the Attribute instance to be selected for the Attribute as per ETSI TS 104 175 [1] clause 8.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: 2019 [17] format, 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.
join	String	0..1	The type of Linked Entity retrieval to apply (see ETSI TS 104 175 [1] clause 7.7). Allowed values: "inline","@none".
joinLevel	Positive Integer	0..1	Depth of Linked Entity retrieval to apply. Only applicable if join parameter is present.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce a languageMap to a string or string array property in a single preferred language.
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

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

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Attribute Fragment	1	200 OK	A response body containing the JSON-LD representation of the target Attribute. 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.
	Attribute Fragment	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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) or Attribute name is not known to the system, see clause 6.3.2.
	ProblemDetails (see IETF RFC 7807 [20])	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.4.2.

7.5.3.2 PATCH

This method is bound to the "Partial Attribute Update" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.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". The Entity Fragment shall be contained in the HTTP request payload body. Figure 7.5.3.2-1 shows the Partial Attribute Update interaction.

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

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	Attribute Fragment	1	Attribute 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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.5.3.3 PUT

This method is bound to the "Replace Attribute" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.11. 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 7.5.3.3-1 shows the Replace Attribute interaction.

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

Name	Data Type	Cardinality	Remarks
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.5.3.4 DELETE

This method is associated to the operation "Delete Attribute" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.7. 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 7.5.3.4-1 shows the Delete Attribute interaction, Table 7.5.3.4-1 shows the delete parameters to be supported and Table 7.5.3.4-2 describes the request body and possible responses.

Name	Data Type	Cardinality	Remarks
datasetId	String	0..1	Shall be a valid URI. Specifies the datasetId of the dataset to be deleted.
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 ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.6 Resource: entities/{entityId}/attrs/{attrId}/value

7.6.1 Description

This resources represents the value of an attribute of a Entity.

7.6.2 Resource definition

7.6.3 Resource methods

7.6.3.1 GET/HEAD

This method is associated to the operation "Retrieve Attribute Value" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.4.4, providing a value only Attribute Fragment as part of the HTTP response payload body.

The URL parameters that shall be supported by implementations are those defined in Table 7.6.3.1-1, the request headers that shall be supported by implementations are those defined in Table 7.6.3.1-2 and Table 7.6.3.2-1 describes the request body and possible responses.

Name	Data Type	Cardinality
datasetId	String	0..1	Shall be a valid URI, "@none" for return the default Attribute instance. Specifies the datasetId of the Attribute instance to be selected for the Attribute as per ETSI TS 104 175 [1] clause 8.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: 2019 [17] format, 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.
lang	String	0..1	It represents the preferred natural language of the response. It is used to reduce a languageMap to a string or string array property in a single preferred language.
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	value only Attribute Fragment	1	200 OK	A response body (JSON Primitive, Object or Array) containing the value from the target Attribute. 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.
	value only Attribute Fragment	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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an Entity identifier (URI) or Attribute name is not known to the system, see clause 6.3.2.
	ProblemDetails (see IETF RFC 7807 [20])	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.4.2.

7.6.3.2 PUT

This method is associated to the operation "Set Attribute Value" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.2.6, using a value only Attribute Fragment as the HTTP payload request body.

Name	Data Type	Cardinality	Remarks
datasetId	String	0..1	Shall be a valid URI, "@none" for return the default Attribute instance. Specifies the datasetId of the Attribute instance to be selected for the Attribute as per ETSI TS 104 175 [1] clause 8.5.
observedAt	String	0..1	It shall be a DateTime (see ETSI TS 104 175 [1] clause 5.2.2.4). When a Set Attribute Value operation applies to a pre-existing Attribute which previously contained an observedAt sub-attribute, the value held in this query parameter shall be used in preference to the server time.
type	String	0..1	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	value only Attribute Fragment	1	JSON Primitive, Object or Array containing the value to set within the target Attribute.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No content	The Attribute value was updated 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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an Entity identifier or Attribute name is not known to the system, see clause 6.3.2.

7.7 Resource: entityOperations/create

7.7.1 Description

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

7.7.2 Resource definition

Resource URI:

• /entityOperations/create

7.7.3 Resource methods

7.7.3.1 POST

This method is associated to the operation "Batch Entity Creation" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.3.2. Figure 7.7.3.1-1 shows the operation interaction and Table 7.7.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.8 Resource: entityOperations/upsert

7.8.1 Description

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

7.8.2 Resource definition

Resource URI:

• /entityOperations/upsert

7.8.3 Resource methods

7.8.3.1 POST

This method is associated to the operation "Batch Entity Creation or Update (Upsert)" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.3.3. Figure 7.8.3.1-1 shows the operation interaction and Table 7.8.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.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.9 Resource: entityOperations/update

7.9.1 Description

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

7.9.2 Resource definition

Resource URI:

• /entityOperations/update

7.9.3 Resource methods

7.9.3.1 POST

This method is associated to the operation "Batch Entity Update" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.3.4. Figure 7.9.3.1-1 shows the operation interaction and Table 7.9.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.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.10 Resource: entityOperations/merge

7.10.1 Description

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

7.10.2 Resource definition

Resource URI:

• /entityOperations/merge

7.10.3 Resource methods

7.10.3.1 POST

This method is associated to the operation "Batch Entity Merge" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.3.5. Figure 7.10.3.1-1 shows the operation interaction and Table 7.10.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.11 Resource: entityOperations/delete

7.11.1 Description

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

7.11.2 Resource definition

Resource URI:

• /entityOperations/delete

7.11.3 Resource methods

7.11.3.1 POST

This method is associated to the operation "Batch Entity Delete" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.3.6. Figure 7.11.3.1-1 shows the operation interaction and Table 7.11.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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.5.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.12 Resource: entityOperations/query

7.12.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 7.2.3.1, which performs the "Query Entity" operation (defined by ETSI TS 104 175 [1] clause 10.4.3) by means of a GET method. The reason to provide an alternative via POST is that, using GET:

• 1. 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.
• 2. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.

7.12.2 Resource definition

Resource URI:

• /entityOperations/query

7.12.3 Resource methods

7.12.3.1 POST

This method is associated to the operation "Query Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.4.3. Figure 7.12.3.1-1 shows the operation interaction and Table 7.12.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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.
	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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.13 Resource: subscriptions/

7.13.1 Description

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

7.13.2 Resource definition

Resource URI:

• /subscriptions/

7.13.3 Resource methods

7.13.3.1 GET/HEAD

This method is associated to the operation "Query Subscriptions" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.5.5, providing the subscription data as part of the HTTP response payload body. Figure 7.13.3.1-1 shows the Query Subscriptions interaction.

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

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

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

7.13.3.2 POST

This method is bound to the operation "Create Subscription" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.5.2, taking the subscription to be created from the HTTP request payload body. Figure 7.13.3.2-1 shows the Create Subscription interaction and Table 7.13.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 relative path of the created subscription.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.14 Resource: subscriptions/{subscriptionId}

7.14.1 Description

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

7.14.2 Resource definition

Resource URI:

• /subscriptions/{subscriptionId}

Resource URI variables for this resource are defined in Table 7.14.2-1.

Name	Definition
subscriptionId	Id (URI) of the concerned subscription

7.14.3 Resource methods

7.14.3.1 GET/HEAD

This method is associated to the operation "Retrieve Subscription" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.5.4. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 7.14.3.1-1 shows the Retrieve Subscription interaction and Table 7.14.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

7.14.3.2 PATCH

This method is associated to the operation "Update Subscription" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.5.3. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 7.14.3.2-1 shows the Update Subscription interaction and Table 7.14.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

7.14.3.3 DELETE

This method is associated to the operation "Delete Subscription" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.5.6. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 7.14.3.3-1 shows the Delete Subscription interaction and Table 7.14.3.3-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

7.15 Resource: types/

7.15.1 Description

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

7.15.2 Resource definition

Resource URI:

• /types/

7.15.3 Resource methods

7.15.3.1 GET/HEAD

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 ETSI TS 104 175 [1] clauses 10.6.3 and 10.6.4 respectively.

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

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 (ETSI TS 104 175 [1] clause 5.2.6.10.3) is to be returned.

Request Body	Data Type	Cardinality	Remarks
	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 (ETSI TS 104 175 [1] clause 5.2.6.10.5) 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 (ETSI TS 104 175 [1] clause 5.2.6.10.3) is to be returned.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.16 Resource: types/{type}

7.16.1 Description

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

7.16.2 Resource definition

Resource URI:

• /types/{type}

Resource URI variables for this resource are defined in Table 7.16.2-1.

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.

7.16.3 Resource methods

7.16.3.1 GET/HEAD

This method is associated to the operation "Retrieve Available Entity Type Information" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.6.5. The entity type is the value of the resource URI variable "type". Figure 7.16.3.1-1 shows the retrieve available entity type interaction.

Table 7.16.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	1	404 Not Found	It is used when a client provided an entity type not known to the system, see clause 6.3.2.

7.17 Resource: attributes/

7.17.1 Description

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

7.17.2 Resource definition

Resource URI:

• /attributes/

7.17.3 Resource methods

7.17.3.1 GET/HEAD

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 ETSI TS 104 175 [1] clauses 10.6.6 and 10.6.7 respectively.

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

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 (ETSI TS 104 175 [1] clause 5.2.6.10.1) is to be returned.

Request Body	Data Type	Cardinality	Remarks
	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 (ETSI TS 104 175 [1] clause 5.2.6.10.2) 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 (ETSI TS 104 175 [1] clause 5.2.6.10.1) is to be returned.
	ProblemDetails (see IETF RFC 7807 [20])	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.

7.18 Resource: attributes/{attrId}

7.18.1 Description

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

7.18.2 Resource definition

Resource URI:

• /attributes/{attrId}

Resource URI variables for this resource are defined in Table 7.18.2-1.

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.

7.18.3 Resource methods

7.18.3.1 GET/HEAD

This method is associated to the operation "Retrieve Available Attribute Information" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 10.6.8. The attribute is the value of the resource URI variable "attrId". Figure 7.18.3.1-1 shows the retrieve available attribute information interaction.

Table 7.18.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	1	404 Not Found	It is used when a client provided an attribute name not known to the system, see clause 6.3.2.

8 Temporal API resources

8.1 Introduction

Clause 8 defines the resources related to the temporal API.

8.2 Resource: temporal/entities/

8.2.1 Description

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

8.2.2 Resource definition

Resource URI:

• /temporal/entities/

8.2.3 Resource methods

8.2.3.1 GET/HEAD

This method is associated to the operation "Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 11.3.3, 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 8.7. Figure 8.2.3.1-1 shows this interaction.

The URL parameters that shall be supported by implementations are those defined in table 8.2.3.1-1 and table 8.2.3.1-2 describes the request body and possible responses.

Name	Data Type	Cardinality	Remarks
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 ETSI TS 104 175 [1] clause 5.3.2.7. Only applicable if "aggregatedValues" is present in the format or options parameter.
aggrPeriodDuration	String	0..1	It represents the duration of each period used for the aggregation as defined by ETSI TS 104 175 [1] clause 5.3.2.7. 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 format or options parameter.
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 ETSI TS 104 175 [1] clause 8.6).	A synonym for a combination of the pick and q parameters. Deprecated Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.
collation	String	0..1	An ICU collation (see IETF RFC 6067 [16]), When defined, the Entities returned in the payload shall be ordered according to the collation given. It is part of Entity ordering.
coordinates	String	0..1 It shall be one if georel or geometry are present	Coordinates serialized as a string as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
csf	String	0..1	Context Source filter as per ETSI TS 104 175 [1] clause 7.2.3.
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 ETSI TS 104 175 [1] clause 8.5.
endTimeAt	String	0..1	It is representing the endTimeAt parameter as defined by ETSI TS 104 175 [1] clause 7.2.6. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between".
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: 2019 [17] format, 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.
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.
geometry	String	0..1 It shall be 1 if georel or coordinates are present	Geometry as per ETSI TS 104 175 [1] clause 7.2.4. 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 ETSI TS 104 175 [1] clause 5.2.6.4.5).
georel	String	0..1 It shall be 1 if geometry or coordinates are present	Geo relationship as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
idPattern	Regular expression as defined by IEEE 1003.2™-1992 [18]	0..1	Regular expression that shall be matched by entity ids.
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.
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.
lastN	Positive integer	0..1	Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved.
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.
orderBy	String	0..1	The Entity member ("id") appended with an optional sorting style ("asc", "desc")as per ETSI TS 104 175 [1] clause 7.6.2. When defined, the Entities returned in the payload shall be ordered according to members defined. It is part of Entity ordering.
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.
q	String	0..1	Query as per ETSI TS 104 175 [1] clause 7.2.3.
scopeQ	String	0..1	Scope query (see ETSI TS 104 175 [1] clause 7.2.5).
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.
timeAt	String	1	representing the timeAt parameter as defined by ETSI TS 104 175 [1] clause 7.2.6. It shall be a DateTime.
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 ETSI TS 104 175 [1] clause 5.2.4).
timerel	String	1	It represents the temporal relationship as defined by ETSI TS 104 175 [1] clause 7.2.6. Allowed values: "before", "after", "between".
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 ETSI TS 104 175 [1] clause 8.6).	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2. "*" is also allowed as a value and local is implicitly set to true and shall not be explicitly set to false.

Request Body	Data Type	Cardinality	Remarks
	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.
	EntityTemporal[]	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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [20])	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.

8.2.3.2 POST

This method is associated to the operation "Create or Update Temporal Evolution of an Entity" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 11.2.2, taking the temporal representation of Entity to be created from the HTTP request payload body. Figure 8.2.3.2-1 shows this interaction and table 8.2.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 relative path of the created entity.
	N/A	N/A	204 No Content	Upon update success.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

8.3 Resource: temporal/entities/{entityId}

8.3.1 Description

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

8.3.2 Resource definition

Resource URI:

• /temporal/entities/{entityId}

Resource URI variables for this resource are defined in Table 8.3.2-1.

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

8.3.3 Resource methods

8.3.3.1 GET/HEAD

This method is associated to the operation "Retrieve Temporal Evolution of an Entity" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 11.3.2. The Entity identifier is the value of the resource URI variable entityId. Figure 8.3.3.1-1 shows the retrieve temporal representation of an entity interaction.

The URL parameters that shall be supported are those defined in table 8.3.3.1-1 and table 8.3.3.1-2 describes the request body and possible responses.

Name	Data Type	Cardinality	Remarks
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 ETSI TS 104 175 [1] clause 5.3.2.7. Only applicable if "aggregatedValues" is present in the format or options parameter.
aggrPeriodDuration	String	0..1	It represents the duration of each period used for the aggregation as defined by ETSI TS 104 175 [1] clause 5.3.2.7. 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 format or options parameter.
attrs	Comma separated list of strings	0..1	A synonym for the pick parameter, except that id, type, scope are not allowed. 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.
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 ETSI TS 104 175 [1] clause 8.5.
endTimeAt	String	0..1 It shall be 1 if timerel is equal to "between"	It represents the endTimeAt parameter as defined by ETSI TS 104 175 [1] clause 7.2.6. It shall be a DateTime.
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.
lastN	Positive integer	0..1	Only the last n Attribute instances (under the concerned time interval) shall be retrieved.
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.
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.
timeAt	String	0..1 It shall be 1 if timerel is present	It represents the timeAt parameter as defined by ETSI TS 104 175 [1] clause 7.2.6. It shall be a DateTime.
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 ETSI TS 104 175 [1] clause 5.2.4).
timerel	String	0..1 It shall be 1 if timeAt is present	It represents the Temporal Relationship as defined by ETSI TS 104 175 [1] clause 7.2.6. Allowed values: "before", "after", "between".

Request Body	Data Type	Cardinality	Remarks
	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.
	EntityTemporal	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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

8.3.3.2 DELETE

This method is associated to the operation "Delete Temporal Evolution of an Entity" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 11.2.7. The Entity identifier is the value of the resource URI variable entityId. Figure 8.3.3.2-1 shows the delete entity interaction and Table 8.3.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

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

8.4.1 Description

This resource represents all the Attributes of a Temporal Evolution of an Entity.

8.4.2 Resource definition

Resource URI:

• /temporal/entities/{entityId}/attrs/

Resource URI variables for this resource are defined in Table 8.4.2-1.

Name	Definition
entityId	Id (URI) of the concerned entity

8.4.3 Resource methods

8.4.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 ETSI TS 104 175 [1] clause 11.2.3. 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 8.4.3.1-1 shows the Add Attributes interaction and Table 8.4.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

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

8.5.1 Description

This resource represents an Attribute of a Temporal Evolution of an Entity.

8.5.2 Resource definition

Resource URI:

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

Resource URI variables for this resource are defined in Table 8.5.2-1.

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

8.5.3 Resource methods

8.5.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 ETSI TS 104 175 [1] clause 11.2.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. Figure 8.5.3.1-1 shows the "Delete Attribute from Temporal Evolution of an Entity" interaction, table 8.5.3.1-1 shows the delete parameters to be supported and table 8.5.3.1-2 describes the request body and possible responses.

name	Data Type	Cardinality	Remarks
datasetId	String	0..1	Shall be a valid URI. Specifies the datasetId of the dataset to be deleted.
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.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

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

8.6.1 Description

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

8.6.2 Resource definition

Resource URI:

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

Resource URI variables for this resource are defined in Table 8.6.2-1.

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

8.6.3 Resource methods

8.6.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 ETSI TS 104 175 [1] clause 11.2.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. The instance identifier is the value of the resource URI variable instanceId. Figure 8.6.3.1-1 shows the Modify Attribute instance interaction and Table 8.6.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

8.6.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 ETSI TS 104 175 [1] clause 11.2.6. 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 8.6.3.2-1 shows the Delete Attribute instance interaction and Table 8.6.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

8.7 Resource: temporal/entityOperations/query

8.7.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 8.2.3.1, which performs the "Query Temporal Evolution of Entities" (defined by ETSI TS 104 175 [1] clause 11.3.3) operation by means of a GET method. The reason to provide an alternative via POST is that, using GET:

• 1. 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.
• 2. There is a need to URL-encode the resulting URL. By using POST, there is no need to url-encode.

8.7.2 Resource definition

Resource URI:

• /temporal/entityOperations/query

8.7.3 Resource methods

8.7.3.1 POST

This method is associated to the operation "Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 11.3.3. Figure 8.7.3.1-1 shows the operation interaction and Table 8.7.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

9 Registry API resources

9.1 Introduction

Clause 9 defines the resources related to creating, managing, retrieving, discovering and subscribing to Context Source Registrations.

9.2 Resource: csourceRegistrations/

9.2.1 Description

This resource represents the Context Source Registrations known to an NGSI-LD system.

9.2.2 Resource definition

Resource URI:

• /csourceRegistrations/

9.2.3 Resource methods

9.2.3.1 GET/HEAD

This method is associated to the operation "Query Context Source Registrations" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.3.3, 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 9.2.3.1-1 shows the Query Context Source Registrations interaction.

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

Name	Data Type	Cardinality	Remarks
attrs	Comma separated list strings	0..1 At least one among: type, attrs, q, or georel shall be present.	A synonym for a combination of the pick and q members. Deprecated Each String is an Attribute (Property or Relationship) name. List of Attributes (Properties or Relationships) to be retrieved.
coordinates	String	0..1 It shall be one if geometry or georel are present.	Coordinates serialized as a string as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
csf	String	0..1	Context Source filter as per ETSI TS 104 175 [1] clause 7.2.3.
endTimeAt	String	0..1	It represents the endTimeAt parameter as defined by ETSI TS 104 175 [1] clause 7.2.6. It shall be a DateTime. Cardinality shall be 1 if timerel is equal to "between".
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 ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
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 top-level geometry field.
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.
georel	String	0..1 It shall be 1 if geometry or coordinates are present.	Geo relationship as per ETSI TS 104 175 [1] clause 7.2.4. It is part of geoquery.
id	Comma separated list of strings	0..1	Each String shall be a valid URI. List of entity ids to be retrieved.
idPattern	Regular expression as defined by IEEE 1003.2™-1992 [18]	0..1	Regular expression that shall be matched by entity ids satisfying the query
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.
omit	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name).
pick	Comma separated list of strings	0..1	Each String is an Entity member ("id", "type", "scope" or a projected Attribute name).
q	String	0..1 At least one among: type, attrs, q, or georel shall be present.	Query as per ETSI TS 104 175 [1] clause 7.2.3.
scopeQ	String	0..1	Scope query (see ETSI TS 104 175 [1] clause 7.2.5).
timeAt	String	0..1	It represents the timeAt parameter as defined by ETSI TS 104 175 [1] clause 7.2.6. It shall be a DateTime. Cardinality shall be 1 if timerel is present.
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 ETSI TS 104 175 [1] clause 5.2.4).
timerel	String	0..1	It represents the temporal relationship as defined by ETSI TS 104 175 [1] clause 7.2.6. Allowed values: "before", "after", "between".
type	String	0..1 At least one among: type, attrs, q, or georel shall be present.	Selection of Entity Types as per ETSI TS 104 175 [1] clause 7.2.2.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

9.2.3.2 POST

This method is bound to the operation "Register Context Source" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.2.2, taking the context source registration to be created from the HTTP request payload body. Figure 9.2.3.2-1 shows the Register Context Source interaction and Table 9.2.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 relative path of the created context source registration.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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 [20])	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.

9.3 Resource: csourceRegistrations/{registrationId}

9.3.1 Description

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

9.3.2 Resource definition

Resource URI:

• /csourceRegistrations/{registrationId}

Resource URI variables for this resource are defined in Table 9.3.2-1.

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

9.3.3 Resource methods

9.3.3.1 GET/HEAD

This method is associated with the operation "Retrieve Context Source Registration" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.3.2. The registration identifier is the value of the resource URI variable "registrationId". Figure 9.3.3.1-1 shows the Retrieve Context Source Registration interaction and Table 9.3.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

9.3.3.2 PATCH

This method is bound to the "Update Context Source Registration" operation and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.2.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 9.3.3.2-1 shows the Update Context Source Registration interaction and Table 9.3.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

9.3.3.3 DELETE

This method is associated to the operation "Delete Context Source Registration" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.2.4. The context source registration identifier is the value of the resource URI variable "registrationId". Figure 9.3.3.3-1 shows the Delete Context Source Registration interaction and Table 9.3.3.3-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

9.4 Resource: csourceSubscriptions/

9.4.1 Description

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

9.4.2 Resource definition

Resource URI:

• /csourceSubscriptions/

9.4.3 Resource methods

9.4.3.1 GET/HEAD

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

Request Body	Data Type	Cardinality	Remarks
	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 relative path of the created context source registration subscription.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

9.4.3.2 POST

This method is associated to the operation "Query Context Source Registration Subscriptions" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.4.5, providing the context source registration subscription data as part of the HTTP response payload body. Figure 9.4.3.2-1 shows the Query Context Source Registration Subscriptions interaction.

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

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

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

9.5 Resource: csourceSubscriptions/{subscriptionId}

9.5.1 Description

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

9.5.2 Resource definition

Resource URI:

• /csourceSubscriptions/{subscriptionId}

Resource URI variables for this resource are defined in Table 9.5.2-1.

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

9.5.3 Resource methods

9.5.3.1 GET/HEAD

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

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

9.5.3.2 PATCH

This method is associated to the operation "Update Context Source Registration Subscription" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.4.3. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 9.5.3.2-1 shows the Update Context Source Registration Subscription interaction and Table 9.5.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	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.

9.5.3.3 DELETE

This method is associated to the operation "Delete Context Source Registration Subscription" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 12.4.6. The subscription identifier is the value of the resource URI variable "subscriptionId". Figure 9.5.3.3-1 shows the Delete Context Source Registration Subscription interaction and Table 9.5.3.3-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.

10 Storing, Managing and Serving @contexts Resources

10.1 Introduction

Clause 10 defines the resources related to the management of JSON-LD @contexts in an NGSI-LD system. An NGSI-LD system may store @contexts in its internal @context storage, and it may serve them to clients. The resources defined in this clause allow clients to list, add, delete, and retrieve @contexts.

10.2 Resource: jsonldContexts/

10.2.1 Description

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

10.2.2 Resource definition

Resource URI:

• /jsonldContexts/

10.2.3 Resource methods

10.2.3.1 GET/HEAD

This method is associated to the operation "List @contexts" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 13.3, and it provides information about stored @contexts as part of the HTTP response payload body. Figure 10.2.3.1-1 shows the List @contexts interaction.

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

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".

Request Body	Data Type	Cardinality	Remarks
	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 by ETSI TS 104 175 [1] clause 13.3.5, representing metadata about stored @contexts.
	ProblemDetails (see IETF RFC 7807 [20])	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.

10.2.3.2 POST

This method is bound to the operation "Add @context" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 13.2, taking the @context to be added from the HTTP request payload body. Figure 10.2.3.2-1 shows the Add @context interaction and Table 10.2.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 relative path of the added @context.
	ProblemDetails (see IETF RFC 7807 [20])	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.

10.3 Resource: jsonldContexts/{contextId}

10.3.1 Description

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

10.3.2 Resource definition

Resource URI:

• /jsonldContexts/{contextId}

Resource URI variables for this resource are defined in Table 10.3.2-1.

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.

10.3.3 Resource methods

10.3.3.1 GET/HEAD

This method is associated to the operation "Serve @context" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 13.4. The @context identifier is the value of the resource URI variable "contextId". Figure 10.3.3.1-1 shows the HTTP Serve @context interaction.

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

Name	Data Type	Cardinality	Remarks
core	String	0..1	A semantically versioned string in the form major.minor, which conforms to a version of the NGSI-LD specification. When present the endpoint returns an array consisting of the user @context URL and the core @context URL.
details	Boolean	0..1	Whether the content of the @context or its metadata is requested.

Request Body	Data Type	Cardinality	Remarks
	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 core is present response body contains a JSON object that has a root node named @context holding an array of URLs matching to JSON-LD "local context" and core context. If the parameter details is true, response body contains a JSON object as defined in ETSI TS 104 175 [1] clause 13.4.5, which metadata of a JSON-LD "local context". The core if present is ignored.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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 [20])	1	422 Unprocessable	It is used when a client indicated an @context of type "Cached", see clause 6.3.2.

10.3.3.2 DELETE

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

Name	Data Type	Cardinality	Remarks
reload	Boolean	0..1	Indicates to perform a download and replace of the @context, as specified in ETSI TS 104 175 [1] clause 13.5.4.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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 [20])	1	504 Gateway Timeout	It is used when re-downloading fails.

11 Context Source Entity mapping resources

11.1 Introduction

Clause 11 defines the resources related to creating and managing Entity Maps.

11.2 Resource: entityMaps/

11.2.1 Description

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

11.2.2 Resource definition

Resource URI:

• /entityMaps/

11.2.3 Resource methods

11.2.3.1 GET/HEAD

This method is associated to the operation "Create EntityMap for Query Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 14.5, 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 11.2.3.2. Figure 11.2.3.1-1 shows the Create EntityMap for Query Entities interaction.

The URL parameters that shall be supported by implementations are the same as those for Query Entities and can be found in table 7.2.3.1-1. Table 11.2.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 ETSI TS 104 175 [1] clause 9.5.3. The response shall also include a "Preference-Applied" HTTP header set to "ngsi-ld=<conformant-version>".
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	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.4.2.

11.2.3.2 POST

This method is associated to the operation "Create EntityMap for Query Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 14.5. Figure 11.2.3.2-1 shows the operation interaction and Table 11.2.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

11.3 Resource: temporal/entityMaps

11.3.1 Description

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

11.3.2 Resource definition

Resource URI:

• /temporal/entityMaps/

11.3.3 Resource methods

11.3.3.1 GET/HEAD

This method is associated to the operation "Create EntityMap for Query Temporal Evolution of Entities" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 14.6, 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 11.3.3.2. Figure 11.3.3.1-1 shows this interaction.

The URL parameters that shall be supported by implementations are the same as those for Query Temporal Evolution of Entities and can be found in table 8.2.3.1-1. Table 11.3.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

11.3.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 ETSI TS 104 175 [1] clause 14.6. Figure 11.3.3.2-1 shows the operation interaction and Table 11.3.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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.

11.4 Resource: entityMaps/{entityMapId}

11.4.1 Description

This resource represents an EntityMap available in an NGSI-LD system's internal storage or memory.

11.4.2 Resource definition

Resource URI:

• /entityMaps/{entityMapId}

Resource URI variables for this resource are defined in Table 11.4.2-1.

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

11.4.3 Resource methods

11.4.3.1 GET/HEAD

This method is associated to the operation "Retrieve EntityMap" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 14.2. The EntityMap identifier is the value of the resource URI variable "entityMapId". Figure 11.4.3.1-1 shows the Retrieve EntityMap interaction and Table 11.4.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	1	404 Not Found	It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

11.4.3.2 PATCH

This method is associated to the operation "Update EntityMap" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 14.3. The EntityMap identifier is the value of the resource URI variable "entityMapId". Figure 11.4.3.2-1 shows the Update EntityMap interaction and Table 11.4.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	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 [20])	1	404 Not Found	It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

11.4.3.3 DELETE

This method is associated to the operation "Delete EntityMap" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 14.4. The Entity identifier is the value of the resource URI variable "contextId". Figure 11.4.3.3-1 shows the delete entity interaction and Table 11.4.3.3-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an @context identifier not known to the system, see clause 6.3.2.

12 Context Source identity information resources

12.1 Introduction

This clause defines the resources used to expose identity information about a Context Source.

12.2 Resource: info/sourceIdentity

12.2.1 Description

This resource represents identity information about the Context Source itself.

12.2.2 Resource definition

Resource URI:

• /info/sourceIdentity

12.2.3 Resource methods

12.2.3.1 GET/HEAD

This method is associated to the operation "Retrieve Context Source Identity Information" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 15.2. Figure 12.2.3.1-1 shows the Retrieve Context Source Identity Information interaction and Table 12.2.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	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 [20])	1	501 Not Implemented	It is used by Context Sources to indicate that retrieval of the Context Source information is unsupported see ETSI TS 104 175 [1] clause 15.2.4.

13 Snapshot functionality resources

13.1 Introduction

Clause 13 defines the resources related to creating and managing Snapshots.

13.2 Resource: snapshots/

13.2.1 Description

This resource represents Snapshots available in an NGSI-LD system.

13.2.2 Resource definition

Resource URI:

• /snapshots/

13.2.3 Resource methods

13.2.3.1 POST

This method is associated to the operation "Create Snapshot" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 16.2. Figure 13.2.3.1-1 shows the operation interaction and Table 13.2.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	Snapshot	1	Payload body in the request contains a JSON-LD object which represents parameters for the snapshot to be created.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	202 Accepted	The HTTP response shall include a "Location" HTTP header that contains the relative path of the snapshot being created.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	409 Conflict	It is used to indicate that a Snapshot having the Snapshot identifier included in the request body already exists, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

13.2.3.2 DELETE

This method is associated to the operation "Purge Snapshots" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 16.7. Figure 13.2.3.2-1 shows the Purge Snapshot interaction.

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

Name	Data Type	Cardinality	Remarks
q	String	1	Query as per ETSI TS 104 175 [1] clause 7.2.3, restricted to members of the Snapshot data type.

Request Body	Data Type	Cardinality	Remarks
	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 some or all of the Snapshots 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 Snapshots, while the second array (errors) contains information about the error for each of the Snapshots that could not be deleted. There is no restriction as to the order of the Snapshots IDs in the arrays.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided a filter not matching any Snapshots, see clause 6.3.2.

13.3 Resource: snapshots/{snapshotId}

13.3.1 Description

This resource represents a snapshot in an NGSI-LD system.

13.3.2 Resource definition

esource URI:

• /snapshots/{snapshotId}

Resource URI variables for this resource are defined in Table 13.3.2-1.

Name	Definition
snapshotId	Id (URI) of the Snapshot whose status is to be retrieved or updated, or the Snapshot to be deleted.

13.3.3 Resource methods

13.3.3.1 GET/HEAD

This method is associated to the operation "Retrieve Snapshot Status" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 16.4. The Snapshot identifier is the value of the resource URI variable "snapshotId". Figure 13.3.3.1-1 shows the Retrieve Snapshot Status interaction and Table 13.3.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Snapshot	1	200 OK	A response body containing the JSON-LD representation of the target Snapshot status.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

13.3.3.2 PATCH

This method is associated to the operation "Update Snapshot Status" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 16.5. The Snapshot identifier is the value of the resource URI variable "snapshotId". Figure 13.3.3.2-1 shows the Update Snapshot Status interaction and Table 13.3.3.2-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	Snapshot Fragment	1	Payload body in the request contains a JSON-LD object which represents the Snapshot fragment with which the Snapshot status is to be updated.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	Snapshot	1	200 OK	A response body containing the JSON-LD representation of the updated Snapshot status.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided an EntityMap identifier not known to the system, see clause 6.3.2.

13.3.3.3 DELETE

This method is associated to the operation "Delete Snapshot" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 16.6. The Snapshot identifier is the value of the resource URI variable "snapshotId". Figure 13.3.3.3-1 shows the Delete Snapshot interaction and Table 13.3.3.3-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	N/A	N/A
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	204 No Content
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided a snapshot identifier not known to the system, see clause 6.3.2.

13.4 Resource: snapshots/{snapshotId}/clone

13.4.1 Description

This resource enables the cloning of a snapshot in an NGSI-LD system.

13.4.2 Resource definition

Resource URI:

• /snapshots/{snapshotId}/clone

Resource URI variables for this resource are defined in Table 13.4.2-1.

Name	Definition
snapshotId	Id (URI) of the Snapshot to be queried or deleted.

13.4.3 Resource methods

13.4.3.1 POST

This method is associated to the operation "Clone Snapshot" and shall exhibit the behaviour defined by ETSI TS 104 175 [1] clause 16.3. The Snapshot identifier is the value of the resource URI variable "snapshotId". Figure 13.4.3.1-1 shows the Clone Snapshot interaction and Table 13.4.3.1-1 describes the request body and possible responses.

Request Body	Data Type	Cardinality	Remarks
	Snapshot	1	Payload body in the request contains a JSON-LD object which represents parameters for the cloned snapshot.
Response Body	Data Type	Cardinality	Response Codes	Remarks
	N/A	N/A	202 Accepted	The HTTP response shall include a "Location" HTTP header that contains the relative path of the snapshot being cloned.
	ProblemDetails (see IETF RFC 7807 [20])	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 [20])	1	404 Not Found	It is used when a client provided a Snapshot identifier (URI) not known to the system, see clause 6.3.2.
	ProblemDetails (see IETF RFC 7807 [20])	1	409 Conflict	It is used to indicate that the Snapshot having the Snapshot identifier included in the request body already exists, see clause 6.3.2. In the returned ProblemDetails structure, the detail attribute should convey more information about the error.

Annex A informative: Examples of using the HTTP binding of the API

A.1 Introduction

This clause introduces some simple usage examples of the NGSI-LD API (HTTP REST binding). They are not intended to be exhaustive but just a sample for helping readers to understand better the present document. ETSI ISG CIM published a Developer's Primer with many more examples, see ETSI GR CIM 008 [i.8].

A.2 Entity Examples

A.2.1 Create Entity of Type Vehicle

A.2.1.1 Introduction

A.2.1.2 HTTP request

A.2.1.2.1 Creation using a JSON-LD body and no Link header

POST /ngsi-ld/v1/entities/

Request Headers

• Content-Type: application/ld+json
• Content-Length: 927

Request Body

A.2.1.2.2 Creation using a JSON body and Link Header

POST /ngsi-ld/v1/entities/

Request Headers

• Content-Type: application/json
• Content-Length: 783

• Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Request Body

A.2.1.3 HTTP response

Status Code: 201 Created

Response Headers

• Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567

A.2.2 Query Entities

A.2.2.1 Introduction

A.2.2.2 HTTP request

A.2.2.2.1 Query requesting a JSON-LD Response

GET /ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=simplified

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.2.2.2.2 Query requesting a JSON Response

GET /ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=simplified

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.2.2.3 HTTP response

A.2.2.3.1 JSON-LD Response

The JSON-LD response contains a JSON-LD body with @context and returns no json-ld Link Header.

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Optional Response Header

• Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;

  rel="profile"

Response Body

A.2.2.3.2 JSON Response

The JSON only response contains a json-ld Link header and returns a JSON body without an @context.

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Optional Response Header

• Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;

  rel="profile"

Response Body

A.2.3 Query Entities (pagination)

A.2.3.1 Introduction

A.2.3.2 HTTP request

GET /ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=2

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.2.3.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

• Link: <​http://<​context-broker>/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=0>;

  rel="prev"

• Link: <​http://<​context-broker>/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=4>;

  rel="next"

Optional Response Header

• Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;

  rel="profile"

Response Body

A.2.4 Query Entities (natural language filtering)

A.2.4.1 Introduction

A.2.4.2 HTTP request

GET /ngsi-ld/v1/entities/?type=Vehicle&pick=id,type,marque&q=marque[en-GB]=="Vauxhall Viva"&format=simplified&lang=de

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.2.4.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Optional Response Header

• Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;

  rel="profile"

Response Body

A.2.5 Query Entities (preference)

A.2.5.1 Introduction

A.2.5.2 HTTP request

GET /ngsi-ld/v1/entities/?type=Vehicle&pick=id,type,marque&format=normalized

Request Headers

• Accept: application/json
• Prefer: ngsi-ld=1.3

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.2.5.3 HTTP response

Status Code: 203 Non-Authoritative Information

Response Headers

• Content-Type: application/json
• Preference-Applied: ngsi-ld=1.3

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.3>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Optional Response Header

• Link: <​https://uri.etsi.org/ngsi-ld/profile/1.3>;

  rel="profile"

Response Body

A.2.6 Scope Queries

A.2.6.1 Introduction

A.2.6.2 HTTP request

GET /ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/parking.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.2.6.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Optional Response Header

• Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;

  rel="profile"

Response Body

A.3 Temporal Entity Examples

A.3.1 Temporal Query

A.3.1.1 Introduction

A.3.1.2 HTTP request #1

GET /ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&pick=id,type,speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.3.1.3 HTTP response #1

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Response Body

A.3.1.4 HTTP request #2

GET /ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&pick=id,type,speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.3.1.5 HTTP response #2

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Response Body

A.3.1.6 HTTP request #3

GET /ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&pick=id,type,speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&firstN=2

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.3.1.7 HTTP response #3

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

• Link: <​http://<​context-broker>/ngsi-ld/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&pick=id,type,speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&firstN=2&offsetN=2>;

  rel="intervalafter"; type="application/ld+json"

Response Body

A.3.2 Temporal Query (simplified representation)

A.3.2.1 Introduction

A.3.2.2 HTTP request

GET /ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&pick=id,type,speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=temporalValues

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.3.2.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Response Body

A.3.3 Temporal Query (aggregated representation)

A.3.3.1 Introduction

A.3.3.2 HTTP request

GET /ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&pick=id,type,speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=aggregatedValues

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.3.3.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Response Body

A.3.4 Temporal Scope Queries

A.3.4.1 Introduction

A.3.4.2 HTTP request

GET /ngsi-ld/v1/temporal/entities/?type=Vehicle&pick=id,type,speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ="/Madrid/Centro"

Request Headers

• Accept: application/ld+json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.3.4.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/ld+json

Response Body

Vehicle B9211 has already been within the Scope /Madrid/Centro before the beginning of the request interval, whereas Vehicle A8311 only entered the Scope within the request interval. Thus in the latter case only Property values are included that have been observed after the Scope has become valid.

A.4 Type Examples

A.4.1 Retrieve available Entity Types

A.4.1.1 Introduction

A.4.1.2 HTTP request

GET /ngsi-ld/v1/types

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.4.1.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response Body

A.4.2 Retrieve details of available Entity Types

A.4.2.1 Introduction

A.4.2.2 HTTP request

GET /ngsi-ld/v1/types?details=true

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.4.2.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response Body

A.4.3 Retrieve available Entity Type information

A.4.3.1 Introduction

A.4.3.2 HTTP request

GET /ngsi-ld/v1/types/Vehicle

[Alternative with FQN: GET /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.4.3.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response Body

A.5 Attribute Examples

A.5.1 Retrieve available Attributes

A.5.1.1 Introduction

A.5.1.2 HTTP request

GET /ngsi-ld/v1/attributes

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.5.1.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response Body

A.5.2 Retrieve details of available Attributes

A.5.2.1 Introduction

A.5.2.2 HTTP request

GET /ngsi-ld/v1/attributes?details=true

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.5.2.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response Body

A.5.3 Retrieve available Attribute information

A.5.3.1 Introduction

A.5.3.2 HTTP request

GET /ngsi-ld/v1/attributes/brandName

[ Alternative with FQN: GET /ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName ]

Request Headers

• Accept: application/json

• Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

A.5.3.3 HTTP response

Status Code: 200 OK

Response Headers

• Content-Type: application/json

• Link: <​http://<​context-broker>/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;

  rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response Body

Annex B informative: Conventions and syntax guidelines

When new terms are defined, they are marked in bold, and terms are capitalized thereafter.

API Parameter names are always in lowercase.

Entity Types are defined using lowercase but with a starting capital letter.

JSON-LD nodes and terms are always defined using camel case notation starting with lower case.

When referring to special terms, data types or words defined previously in the present document or by other referenced specifications, italics format is used.

When referring to literal strings double quotes are used.

When referring to the JSON-LD Context the mnemonic text string @context is used as a placeholder.

All the dates and times are given in UTC format.

The measurement units used in the API are those defined by the International System of Units.

When defining application-specific elements or API extensions the same conventions and syntax guidelines should be followed.

Annex C informative: Change history

Date	Version	Information about changes
2026-01	1.0.0	Initialized with content taken from CIM009 (2025/07, V1.9.1)
2026-09	1.1.1	First published version

History

Version	Date	Status
V1.1.1	September 2026	Published