diff --git a/md/annex-a.md b/md/annex-a.md index 6c1c980355127b8845ae1b7275b131e90ec4c5c3..b581c46f58a7de00785b708c45669f5adbdda3c7 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -7,9 +7,11 @@ 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.6]. -## A.2 Create Entity of Type Vehicle +## A.2 Entity Examples -### A.2.1 Introduction +### A.2.1 Create Entity of Type Vehicle + +#### A.2.1.1 Introduction @@ -22,9 +24,9 @@ This example illustrates how to create a new Entity of type -### A.2.2 HTTP request +#### A.2.1.2 HTTP request -#### A.2.2.1 Creation using a JSON-LD body and no Link header +##### A.2.1.2.1 Creation using a JSON-LD body and no Link header **POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} @@ -83,25 +85,26 @@ This example illustrates how to create a new Entity of type } ``` -#### A.2.2.2 Creation using a JSON body and Link Header +##### A.2.1.2.2 Creation using a JSON body and Link Header **POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} **Request Headers** -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} - - [Content-Type: application/**json**]{.HTML-Code} - [Content-Length: 783]{.HTML-Code} - +- [Link: + <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} >>> [!note] NOTE: -The URL found within the Link header above only refers to the user +The URL found within the _`json-ld`_ [Link]{.HTML-Code} header above only refers to the user _`@context`_ since the addition of the core _`@context`_ can be implied. >>> @@ -153,7 +156,7 @@ The URL found within the Link header above only refers to the user } ``` -### A.2.3 HTTP response +#### A.2.1.3 HTTP response **Status Code:** 201 Created @@ -161,9 +164,9 @@ The URL found within the Link header above only refers to the user - [Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567]{.HTML-Code} -## A.3 Query Entities +### A.2.2 Query Entities -### A.3.1 Introduction +#### A.2.2.1 Introduction @@ -178,9 +181,9 @@ NGSI-LD Simplified Format. -### A.3.2 HTTP request +#### A.2.2.2 HTTP request -#### A.3.2.1 Query requesting a JSON-LD Response +##### A.2.2.2.1 Query requesting a JSON-LD Response **GET** [/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} @@ -189,11 +192,14 @@ NGSI-LD Simplified Format. - [Accept: application/**ld+json**]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} +- [Link: + <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -#### A.3.2.2 Query requesting a JSON Response +##### A.2.2.2.2 Query requesting a JSON Response **GET** [/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} @@ -202,16 +208,19 @@ NGSI-LD Simplified Format. - [Accept: application/**json**]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} +- [Link: + <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.3.3 HTTP response +#### A.2.2.3 HTTP response -#### A.3.3.1 JSON-LD Response +##### A.2.2.3.1 JSON-LD Response The JSON-LD response contains a JSON-LD body with _`@context`_ and returns no -Link Header. +json-ld [Link]{.HTML-Code} Header. **Status Code:** 200 OK @@ -219,6 +228,26 @@ Link Header. - [Content-Type: application/**ld+json**]{.HTML-Code} +**Optional Response Header** + +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code + .indent} + + [rel="**profile**"]{.HTML-Code .run-on} + + + +>>> [!note] NOTE: + +The version found within the optional _`profile`_ [Link]{.HTML-Code} header indicates that the payload +of this request conforms to the NGSI-LD 1.9 specification. + +>>> + + + + **Response Body** ```json @@ -235,20 +264,30 @@ Link Header. ] ``` -#### A.3.3.2 JSON Response +##### A.2.2.3.2 JSON Response -The JSON only response contains a Link Header and returns a JSON body without an -_`@context`_. +The JSON only response contains a json-ld [Link]{.HTML-Code} header and returns +a JSON body without an _`@context`_. **Status Code:** 200 OK **Response Headers** - [Content-Type: application/**json**]{.HTML-Code} + - [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"]{.HTML-Code} + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** @@ -288,9 +327,9 @@ and therefore fully complies with the JSON-LD Specification [n.8] -## A.4 Query Entities (pagination) +### A.2.3 Query Entities (pagination) -### A.4.1 Introduction +#### A.2.3.1 Introduction @@ -298,115 +337,83 @@ and therefore fully complies with the JSON-LD Specification [n.8] Give back all the Entities of type ["Vehicle"]{.HTML-Code}. Only give back the _`brandName`_ attribute and provide the data in the NGSI-LD -Simplified Format. Limit the number of entities retrieved to 2. +Simplified Format. Limit the number of entities retrieved to two and start from +the third Entity >>> -### A.4.2 HTTP request +#### A.2.3.2 HTTP request **GET** -[/ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2]{.HTML-Variable} +[/ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=2]{.HTML-Variable} **Request Headers** -- [Accept: application/**ld+json**]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/vehicle.jsonld>;]{.HTML-Code + .indent} -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.4.3 HTTP response +#### A.2.3.3 HTTP response **Status Code:** 200 OK **Response Headers** -- [Content-Type: application/**ld+json**]{.HTML-Code} +- [Content-Type: application/**json**]{.HTML-Code} - [Link: - </ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=>; - rel="next"; type="application/ld+json"]{.HTML-Code} - -**Response Body** + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9>;]{.HTML-Code + .indent} -```json -[ - { - "id": "urn:ngsi-ld:Vehicle:B9211", - "type": "Vehicle", - "brandName": "Volvo", - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] - }, - { - "id": "urn:ngsi-ld:Vehicle:A456", - "type": "Vehicle", - "brandName": "Mercedes", - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] - } -] -``` + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -## A.5 Temporal Query +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=0>;]{.HTML-Code + .indent} -### A.5.1 Introduction + [rel="**prev**"]{.HTML-Code .run-on} - +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=4>;]{.HTML-Code + .indent} ->>> [!tip] EXAMPLE 1: + [rel="**next**"]{.HTML-Code .run-on} -Give back the temporal evolution of the attribute _`speed`_ of -Entities of type ["Vehicle"]{.HTML-Code} whose _`brandName`_ -attribute is not ["Mercedes"]{.HTML-Code} between the 1st of August -at noon and the 1st of August at 01 PM. +**Optional Response Header** ->>> +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code + .indent} - + [rel="**profile**"]{.HTML-Code .run-on} ->>> [!tip] EXAMPLE 2: - -Give back the temporal evolution of the attribute _`speed`_ and -_`brandName`_ of Entities of type ["Vehicle"]{.HTML-Code} whose -_`brandName`_ attribute is not ["Mercedes"]{.HTML-Code} between -the 1st of August at noon and the 1st of August at 01 PM. -As _`brandName`_ attribute does not have any temporal evolution, -_`brandName`_ attribute is omitted in the response. - ->>> - - - -### A.5.2 HTTP request #1 - -**GET** -[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z]{.HTML-Variable} - -**Request Headers** +>>> [!note] NOTE: -- [Accept: application/**ld+json**]{.HTML-Code} +The URL found within the _`json-ld`_ [Link]{.HTML-Code} header above refers to the +combination of core and user @contexts. -- [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} +The URL found within the _`prev`_ [Link]{.HTML-Code} header shows the path to the previous two Entities +in the list -### A.5.3 HTTP response #1 +The URL found within the _`next`_ [Link]{.HTML-Code} header shows the path to the next two Entities +in the list -**Status Code:** 200 OK +The version found within the optional _`profile`_ [Link]{.HTML-Code} header indicates that the payload +of this response conforms to the NGSI-LD 1.9 specification. -**Response Headers** +>>> -- [Content-Type: application/**ld+json**]{.HTML-Code} + **Response Body** @@ -415,118 +422,54 @@ _`brandName`_ attribute is omitted in the response. { "id": "urn:ngsi-ld:Vehicle:B9211", "type": "Vehicle", - "speed": [ - { - "type": "Property", - "value": 120, - "observedAt": "2018-08-01T12:03:00Z" - }, - { - "type": "Property", - "value": 80, - "observedAt": "2018-08-01T12:05:00Z" - }, - { - "type": "Property", - "value": 100, - "observedAt": "2018-08-01T12:07:00Z" - } - ], - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] - } -] -``` - -### A.5.4 HTTP request #2 - -**GET** -[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z]{.HTML-Variable} - -**Request Headers** - -- [Accept: application/**ld+json**]{.HTML-Code} - -- [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} - -### A.5.5 HTTP response #2 - -**Status Code:** 200 OK - -**Response Headers** - -- [Content-Type: application/**ld+json**]{.HTML-Code} - -**Response Body** - -```json -[ + "brandName": "Volvo" + }, { - "id": "urn:ngsi-ld:Vehicle:B9211", + "id": "urn:ngsi-ld:Vehicle:A456", "type": "Vehicle", - "speed": [ - { - "type": "Property", - "value": 120, - "observedAt": "2018-08-01T12:03:00Z" - }, - { - "type": "Property", - "value": 80, - "observedAt": "2018-08-01T12:05:00Z" - }, - { - "type": "Property", - "value": 100, - "observedAt": "2018-08-01T12:07:00Z" - } - ], - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] + "brandName": "Mercedes" } ] ``` -## A.6 Temporal Query (simplified representation) +### A.2.4 Query Entities (natural language filtering) -### A.6.1 Introduction +#### A.2.4.1 Introduction >>> [!tip] EXAMPLE: -Give back the temporal evolution of the _`speed`_ attribute for -Entities of type ["Vehicle"]{.HTML-Code} whose _`brandName`_ -attribute is not ["Mercedes"]{.HTML-Code} between the 1st of August -at noon and the 1st of August at 01 PM. Simplified representation is -required. +Give back all the Entities of type ["Vehicle"]{.HTML-Code} where the +_`marque`_ attribute in British English is ["Vauxhall +Viva"]{.HTML-Code}. Only give back the _`marque`_ attribute and +provide the data in the NGSI-LD Simplified Format and only return language +strings in German. + +Note that the _`marque`_ attribute had been created using a _LanguageProperty_. >>> -### A.6.2 HTTP request +#### A.2.4.2 HTTP request **GET** -[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&format=**temporalValues**]{.HTML-Variable} +[/ngsi-ld/v1/entities/?type=Vehicle&pick=id,type,marque&q=marque[en-GB]=="Vauxhall +Viva"&format=**simplified**&lang=de]{.HTML-Variable} **Request Headers** - [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.6.3 HTTP response +#### A.2.4.3 HTTP response **Status Code:** 200 OK @@ -534,21 +477,21 @@ required. - [Content-Type: application/**ld+json**]{.HTML-Code} +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} + **Response Body** ```json [ { - "id": "urn:ngsi-ld:Vehicle:B9211", + "id": "urn:ngsi-ld:Vehicle:A4567", "type": "Vehicle", - "speed": { - "type": "Property", - "values": [ - [120, "2018-08-01T12:03:00Z"], - [80, "2018-08-01T12:05:00Z"], - [100, "2018-08-01T12:07:00Z"] - ] - }, + "marque": "Opel Karl", "@context": [ "http://example.org/ngsi-ld/latest/vehicle.jsonld", "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" @@ -557,509 +500,428 @@ required. ] ``` -## A.7 Retrieve available Entity Types +### A.2.5 Query Entities (preference) -### A.7.1 Introduction +#### A.2.5.1 Introduction >>> [!tip] EXAMPLE: -Give back all entity types for which entity instances are currently available in -the NGSI-LD system. +Give back all the Entities of type ["Vehicle"]{.HTML-Code}. +Only give back the _`marque`_ attribute, provide the data in the NGSI-LD normalised +format and return the data according to the NGSI-LD 1.3 specification. + + +Note that the _`marque`_ attribute had been previously created using a _LanguageProperty_ >>> -### A.7.2 HTTP request +#### A.2.5.2 HTTP request -**GET** [/ngsi-ld/v1/types]{.HTML-Variable} +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&pick=id,type,marque&format=**normalized**]{.HTML-Variable} **Request Headers** - [Accept: application/**json**]{.HTML-Code} +- [Prefer: ngsi-ld=**1.3**]{.HTML-Code} + - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} -### A.7.3 HTTP response + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -**Status Code:** 200 OK +#### A.2.5.3 HTTP response + +**Status Code:** 203 Non-Authoritative Information **Response Headers** - [Content-Type: application/**json**]{.HTML-Code} +- [Preference-Applied: ngsi-ld=**1.3**]{.HTML-Code} + - [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"]{.HTML-Code} + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=**1.3**>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Optional Response Header** + +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.3**>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** ```json -{ - "id": "urn:ngsi-ld:EntityTypeList:34534657", - "type": "EntityTypeList", - "typeList": [ - "Vehicle", - "OffStreetParking", - "http://example.org/parking/ParkingSpot" - ] -} +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "marque": { + "type": "Property", + "value": { + "en-gb": "Vauxhall Viva", + "de": "Opel Karl" + } + } + } +] ``` - >>> [!note] NOTE: -All entity types that can be found in the provided _`@context`_ -are given as short names, the others as Fully Qualified Names (FQNs). +Since subtypes of _Property_ had not been defined by NGSI-LD 1.3 specification, +the _`marque`_ _LanguageProperty_ is returned as a _Property_. The status code +and [Preference-Applied]{.HTML-Code} header indicate that a change has occurred. >>> -## A.8 Retrieve details of available Entity Types +### A.2.6 Scope Queries -### A.8.1 Introduction +#### A.2.6.1 Introduction >>> [!tip] EXAMPLE: -Give back the details of all entity types for which entity instances are -currently available in the NGSI-LD system. +Give back all the Entities of type ["OffStreetParking"]{.HTML-Code} that are +within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. >>> -### A.8.2 HTTP request +#### A.2.6.2 HTTP request -**GET** [/ngsi-ld/v1/types?details=true]{.HTML-Variable} +**GET** +[/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable} **Request Headers** -- [Accept: application/**json**]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/parking.jsonld>;]{.HTML-Code + .indent} -### A.8.3 HTTP response + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.2.6.3 HTTP response **Status Code:** 200 OK **Response Headers** -- [Content-Type: application/**json**]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} -- [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"]{.HTML-Code} +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** ```json [ { - "id": "http://example.org/vehicle/Vehicle", - "type": "EntityType", - "typeName": "Vehicle", - "attributeNames": ["brandName", "isParked", "location", "speed"] - }, - { - "id": "http://example.org/parking/OffStreetParking", - "type": "EntityType", - "typeName": "OffStreetParking", - "attributeNames": [ - "availableSpotNumber", - "isNextToBuilding", - "location", - "totalSpotNumber" + "id": "urn:ngsi-ld:OffStreetParking:Downtown1", + "type": "OffStreetParking", + "scope": "/Madrid/Centro", + "name": { + "type": "Property", + "value": "Downtown One" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 200 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.5, 41.2] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" ] }, { - "id": "http://example.org/parking/ParkingSpot", - "type": "EntityType", - "typeName": "http://example.org/parking/ParkingSpot", - "attributeNames": ["location", "http://example.org/parking/status"] + "id": "urn:ngsi-ld:OffStreetParking:Corte4", + "type": "OffStreetParking", + "scope": ["/Madrid/Cortes", "/Company894/UnitC"], + "name": { + "type": "Property", + "value": "Corte4" + }, + "availableSpotNumber": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z", + "reliability": { + "type": "Property", + "value": 0.7 + }, + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Camera:C1" + } + }, + "totalSpotNumber": { + "type": "Property", + "value": 100 + }, + "location": { + "type": "GeoProperty", + "value": { + "type": "Point", + "coordinates": [-8.6, 41.3] + } + }, + "@context": [ + "http://example.org/ngsi-ld/latest/parking.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] } ] ``` +## A.3 Temporal Entity Examples + +### A.3.1 Temporal Query + +#### A.3.1.1 Introduction + ->>> [!note] NOTE: +>>> [!tip] EXAMPLE 1: -The type name of all entity types and all attribute names that can be found in -the provided _`@context`_ are given as short names, the others as -Fully Qualified Names (FQNs). The _`id`_ is always an FQN. +Give back the temporal evolution of the attribute _`speed`_ of +Entities of type ["Vehicle"]{.HTML-Code} whose _`brandName`_ +attribute is not ["Mercedes"]{.HTML-Code} between the 1st of August +at noon and the 1st of August at 01 PM. >>> -## A.9 Retrieve available Entity Type information - -### A.9.1 Introduction - ->>> [!tip] EXAMPLE: +>>> [!tip] EXAMPLE 2: -Give back the details of entity type ["Vehicle"]{.HTML-Code} (for which entity -instances are currently available in the NGSI-LD system). +Give back the temporal evolution of the attribute _`speed`_ and +_`brandName`_ of Entities of type ["Vehicle"]{.HTML-Code} whose +_`brandName`_ attribute is not ["Mercedes"]{.HTML-Code} between +the 1st of August at noon and the 1st of August at 01 PM. +As _`brandName`_ attribute does not have any temporal evolution, +_`brandName`_ attribute is omitted in the response. >>> -### A.9.2 HTTP request - -**GET** [/ngsi-ld/v1/types/Vehicle]{.HTML-Variable} +#### A.3.1.2 HTTP request #1 -[Alternative with FQN: **GET** -[/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]{.HTML-Variable} +**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]{.HTML-Variable} **Request Headers** -- [Accept: application/**json**]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} -### A.9.3 HTTP response + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.3.1.3 HTTP response #1 **Status Code:** 200 OK **Response Headers** -- [Content-Type: application/**json**]{.HTML-Code} - -- [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"]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** ```json -{ - "id": "http://example.org/vehicle/Vehicle", - "type": "EntityTypeInfo", - "typeName": "Vehicle", - "entityCount": 2, - "attributeDetails": [ - { - "id": "http://example.org/vehicle/brandName", - "type": "Attribute", - "attributeName": "brandName", - "attributeTypes": ["Property"] - }, - { - "id": "http://example.org/vehicle/isParked", - "type": "Attribute", - "attributeName": "isParked", - "attributeTypes": ["Relationship"] - }, - { - "id": "https://uri.etsi.org/ngsi-ld/location", - "type": "Attribute", - "attributeName": "location", - "attributeTypes": ["GeoProperty"] - }, - { - "id": "http://example.org/vehicle/speed", - "type": "Attribute", - "attributeName": "speed", - "attributeTypes": ["Property"] - } - ] -} +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 120, + "observedAt": "2018-08-01T12:03:00Z" + }, + { + "type": "Property", + "value": 80, + "observedAt": "2018-08-01T12:05:00Z" + }, + { + "type": "Property", + "value": 100, + "observedAt": "2018-08-01T12:07:00Z" + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] ``` -## A.10 Retrieve available Attributes - -### A.10.1 Introduction - - - ->>> [!tip] EXAMPLE: - -Give back all attribute names for which entity instances are currently available -in the NGSI-LD system that have an attribute with the respective name. - ->>> - - - -### A.10.2 HTTP request +#### A.3.1.4 HTTP request #2 -**GET** [/ngsi-ld/v1/attributes]{.HTML-Variable} +**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]{.HTML-Variable} **Request Headers** -- [Accept: application/**json**]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.10.3 HTTP response +#### A.3.1.5 HTTP response #2 **Status Code:** 200 OK **Response Headers** -- [Content-Type: application/**json**]{.HTML-Code} - -- [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"]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** ```json -{ - "id": "urn:ngsi-ld:AttributeList:56534657", - "type": "AttributeList", - "attributeList": [ - "brandName", - "isParked", - "location", - "speed", - "http://example.org/parking/status" - ] -} +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 120, + "observedAt": "2018-08-01T12:03:00Z" + }, + { + "type": "Property", + "value": 80, + "observedAt": "2018-08-01T12:05:00Z" + }, + { + "type": "Property", + "value": 100, + "observedAt": "2018-08-01T12:07:00Z" + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] ``` - - ->>> [!note] NOTE: - -The attribute names that can be found in the provided -_`@context`_ are given as short names, the others as fully -qualified names (FQNs). - ->>> - - - -## A.11 Retrieve details of available Attributes +### A.3.2 Temporal Query (simplified representation) -### A.11.1 Introduction +#### A.3.2.1 Introduction >>> [!tip] EXAMPLE: -Give back the details of all attributes for which entity instances are currently -available in the NGSI-LD system to which an attribute with the respective -attribute name belongs. +Give back the temporal evolution of the _`speed`_ attribute for +Entities of type ["Vehicle"]{.HTML-Code} whose _`brandName`_ +attribute is not ["Mercedes"]{.HTML-Code} between the 1st of August +at noon and the 1st of August at 01 PM. Simplified representation is +required. >>> -### A.11.2 HTTP request +#### A.3.2.2 HTTP request -**GET** [/ngsi-ld/v1/attributes?details=true]{.HTML-Variable} +**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**]{.HTML-Variable} **Request Headers** -- [Accept: application/**json**]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} -### A.11.3 HTTP response + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.3.2.3 HTTP response **Status Code:** 200 OK **Response Headers** -- [Content-Type: application/**json**]{.HTML-Code} - -- [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"]{.HTML-Code} - -**Response Body** - -```json -[ - { - "id": "http://example.org/vehicle/brandName", - "type": "Attribute", - "attributeName": "brandName", - "typeNames": ["Vehicle"] - }, - { - "id": "http://example.org/vehicle/isParked", - "type": "Attribute", - "attributeName": "isParked", - "typeNames": ["Vehicle"] - }, - { - "id": "https://uri.etsi.org/ngsi-ld/location", - "type": "Attribute", - "attributeName": "location", - "typeNames": [ - "Vehicle", - "OffStreetParking", - "http://example.org/parking/ParkingSpot" - ] - }, - { - "id": "http://example.org/vehicle/speed", - "type": "Attribute", - "attributeName": "speed", - "typeNames": ["Vehicle"] - }, - { - "id": "http://example.org/parking/status", - "type": "Attribute", - "attributeName": "http://example.org/parking/status", - "typeNames": ["http://example.org/parking/ParkingSpot"] - } -] -``` - - - ->>> [!note] NOTE: - -The attribute name and all type names that can be found in the provided -_`@context`_ are given as short names, the others as Fully -Qualified Names (FQNs). The _`id`_ is always an FQN. - ->>> - - - -## A.12 Retrieve available Attribute information - -### A.12.1 Introduction - - - ->>> [!tip] EXAMPLE: - -Give back the details of the attribute named _`brandName`_ (for -which entity instances with an attribute of this name are currently available in -the NGSI-LD system). - ->>> - - - -### A.12.2 HTTP request - -**GET** [/ngsi-ld/v1/attributes/brandName]{.HTML-Variable} - -\[ Alternative with FQN: **GET** -[/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]{.HTML-Variable} -\] - -**Request Headers** - -- [Accept: application/**json**]{.HTML-Code} - -- [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} - -### A.12.3 HTTP response - -**Status Code:** 200 OK - -**Response Headers** - -- [Content-Type: application/**json**]{.HTML-Code} - -- [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"]{.HTML-Code} - -**Response Body** - -```json -{ - "id": "http://example.org/vehicle/brandName", - "type": "Attribute", - "attributeName": "brandName", - "attributeTypes": ["Property"], - "typeNames": ["Vehicle"], - "attributeCount": 2 -} -``` - -## A.13 Query Entities (natural language filtering) - -### A.13.1 Introduction - - - ->>> [!tip] EXAMPLE: - -Give back all the Entities of type ["Vehicle"]{.HTML-Code} where the -_`marque`_ attribute in British English is ["Vauxhall -Viva"]{.HTML-Code}. Only give back the _`marque`_ attribute and -provide the data in the NGSI-LD Simplified Format and only return language -strings in German. - ->>> - - - -### A.13.2 HTTP request - -**GET** -[/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]=="Vauxhall -Viva"&format=**simplified**&lang=de]{.HTML-Variable} - -**Request Headers** - -- [Accept: application/**ld+json**]{.HTML-Code} - -- [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} - -### A.13.3 HTTP response - -**Status Code:** 200 OK - -**Response Headers** - -- [Content-Type: application/**ld+json**]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** ```json [ { - "id": "urn:ngsi-ld:Vehicle:A4567", + "id": "urn:ngsi-ld:Vehicle:B9211", "type": "Vehicle", - "marque": "Opel Karl", + "speed": { + "type": "Property", + "values": [ + [120, "2018-08-01T12:03:00Z"], + [80, "2018-08-01T12:05:00Z"], + [100, "2018-08-01T12:07:00Z"] + ] + }, "@context": [ "http://example.org/ngsi-ld/latest/vehicle.jsonld", "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" @@ -1068,9 +930,9 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} ] ``` -## A.14 Temporal Query (aggregated representation) +### A.3.3 Temporal Query (aggregated representation) -### A.14.1 Introduction +#### A.3.3.1 Introduction @@ -1085,21 +947,23 @@ Give back the maximum and average _`speed`_ of Entities of type -### A.14.2 HTTP request +#### A.3.3.2 HTTP request **GET** -[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&aggrMethods=max,avg&aggrPeriodDuration=PT4M&format=**aggregatedValues**]{.HTML-Variable} +[/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**]{.HTML-Variable} **Request Headers** - [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.14.3 HTTP response +#### A.3.3.3 HTTP response **Status Code:** 200 OK @@ -1133,36 +997,42 @@ Give back the maximum and average _`speed`_ of Entities of type ] ``` -## A.15 Scope Queries +### A.3.4 Temporal Scope Queries -### A.15.1 Introduction +#### A.3.4.1 Introduction >>> [!tip] EXAMPLE: -Give back all the Entities of type ["OffStreetParking"]{.HTML-Code} that are -within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. +Give back the _`speed`_ of all the Entities of type +["Vehicle"]{.HTML-Code} that have been within the Scope +[/Madrid/Centro]{.HTML-Code} between the 1st of August 2018 at noon +and the 1st of August 2018 at 01 PM. Note that the value of the Scope +has to match for the given timeframe, which means it is possible that it has +been set before, e.g. on 1st of August 2018 at 11 AM. >>> -### A.15.2 HTTP request +#### A.3.4.2 HTTP request **GET** -[/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable} +[/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"]{.HTML-Variable} **Request Headers** - [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.15.3 HTTP response +#### A.3.4.3 HTTP response **Status Code:** 200 OK @@ -1175,174 +1045,534 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. ```json [ { - "id": "urn:ngsi-ld:OffStreetParking:Downtown1", - "type": "OffStreetParking", - "scope": "/Madrid/Centro", - "name": { - "type": "Property", - "value": "Downtown One" - }, - "availableSpotNumber": { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "scope": { "type": "Property", - "value": 121, - "observedAt": "2017-07-29T12:05:02Z", - "reliability": { - "type": "Property", - "value": 0.7 - }, - "providedBy": { - "type": "Relationship", - "object": "urn:ngsi-ld:Camera:C1" - } + "values": [["/Madrid/Centro", "2018-08-01T11:00:00Z"]] }, - "totalSpotNumber": { + "speed": { "type": "Property", - "value": 200 - }, - "location": { - "type": "GeoProperty", - "value": { - "type": "Point", - "coordinates": [-8.5, 41.2] - } + "values": [ + [30, "2018-08-01T12:03:00Z"], + [60, "2018-08-01T12:05:00Z"], + [50, "2018-08-01T12:07:00Z"] + ] }, "@context": [ - "http://example.org/ngsi-ld/latest/parking.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" ] }, { - "id": "urn:ngsi-ld:OffStreetParking:Corte4", - "type": "OffStreetParking", - "scope": ["/Madrid/Cortes", "/Company894/UnitC"], - "name": { - "type": "Property", - "value": "Corte4" - }, - "availableSpotNumber": { + "id": "urn:ngsi-ld:Vehicle:A8311", + "type": "Vehicle", + "scope": { "type": "Property", - "value": 121, - "observedAt": "2017-07-29T12:05:02Z", - "reliability": { - "type": "Property", - "value": 0.7 - }, - "providedBy": { - "type": "Relationship", - "object": "urn:ngsi-ld:Camera:C1" - } + "values": [ + [["/Madrid/Centro", "/Company123/UnitA"], "2018-08-01T12:10:00Z"] + ] }, - "totalSpotNumber": { + "speed": { "type": "Property", - "value": 100 - }, - "location": { - "type": "GeoProperty", - "value": { - "type": "Point", - "coordinates": [-8.6, 41.3] - } + "values": [ + [40, "2018-08-01T12:12:00Z"], + [60, "2018-08-01T12:14:00Z"], + [50, "2018-08-01T12:16:00Z"] + ] }, "@context": [ - "http://example.org/ngsi-ld/latest/parking.jsonld", + "http://example.org/ngsi-ld/latest/vehicle.jsonld", "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" ] } ] ``` -## A.16 Temporal Scope Queries +Vehicle [B9211]{.HTML-Code} has already been within the Scope +[/Madrid/Centro]{.HTML-Code} before the beginning of the request interval, +whereas Vehicle [A8311]{.HTML-Code} 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.16.1 Introduction +### A.4.1 Retrieve available Entity Types + +#### A.4.1.1 Introduction >>> [!tip] EXAMPLE: -Give back the _`speed`_ of all the Entities of type -["Vehicle"]{.HTML-Code} that have been within the Scope -[/Madrid/Centro]{.HTML-Code} between the 1st of August 2018 at noon -and the 1st of August 2018 at 01 PM. Note that the value of the Scope -has to match for the given timeframe, which means it is possible that it has -been set before, e.g. on 1st of August 2018 at 11 AM. +Give back all entity types for which entity instances are currently available in +the NGSI-LD system. >>> -### A.16.2 HTTP request +#### A.4.1.2 HTTP request -**GET** -[/ngsi-ld/v1/temporal/entities/?type=Vehicle&attrs=speed,scope&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&scopeQ="/Madrid/Centro"]{.HTML-Variable} +**GET** [/ngsi-ld/v1/types]{.HTML-Variable} **Request Headers** -- [Accept: application/**ld+json**]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; - type="application/ld+json"]{.HTML-Code} + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} -### A.16.3 HTTP response +#### A.4.1.3 HTTP response **Status Code:** 200 OK **Response Headers** -- [Content-Type: application/**ld+json**]{.HTML-Code} +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Response Body** + +```json +{ + "id": "urn:ngsi-ld:EntityTypeList:34534657", + "type": "EntityTypeList", + "typeList": [ + "Vehicle", + "OffStreetParking", + "http://example.org/parking/ParkingSpot" + ] +} +``` + + + + +>>> [!note] NOTE: + +All entity types that can be found in the provided _`@context`_ +are given as short names, the others as Fully Qualified Names (FQNs). + +>>> + + + +### A.4.2 Retrieve details of available Entity Types + +#### A.4.2.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back the details of all entity types for which entity instances are +currently available in the NGSI-LD system. + +>>> + + + +#### A.4.2.2 HTTP request + +**GET** [/ngsi-ld/v1/types?details=true]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.4.2.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} **Response Body** ```json [ { - "id": "urn:ngsi-ld:Vehicle:B9211", - "type": "Vehicle", - "scope": { - "type": "Property", - "values": [["/Madrid/Centro", "2018-08-01T11:00:00Z"]] - }, - "speed": { - "type": "Property", - "values": [ - [30, "2018-08-01T12:03:00Z"], - [60, "2018-08-01T12:05:00Z"], - [50, "2018-08-01T12:07:00Z"] - ] - }, - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + "id": "http://example.org/vehicle/Vehicle", + "type": "EntityType", + "typeName": "Vehicle", + "attributeNames": ["brandName", "isParked", "location", "speed"] + }, + { + "id": "http://example.org/parking/OffStreetParking", + "type": "EntityType", + "typeName": "OffStreetParking", + "attributeNames": [ + "availableSpotNumber", + "isNextToBuilding", + "location", + "totalSpotNumber" ] }, { - "id": "urn:ngsi-ld:Vehicle:A8311", - "type": "Vehicle", - "scope": { - "type": "Property", - "values": [ - [["/Madrid/Centro", "/Company123/UnitA"], "2018-08-01T12:10:00Z"] - ] + "id": "http://example.org/parking/ParkingSpot", + "type": "EntityType", + "typeName": "http://example.org/parking/ParkingSpot", + "attributeNames": ["location", "http://example.org/parking/status"] + } +] +``` + + + +>>> [!note] NOTE: + +The type name of all entity types and all attribute names that can be found in +the provided _`@context`_ are given as short names, the others as +Fully Qualified Names (FQNs). The _`id`_ is always an FQN. + +>>> + + + +### A.4.3 Retrieve available Entity Type information + +#### A.4.3.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back the details of entity type ["Vehicle"]{.HTML-Code} (for which entity +instances are currently available in the NGSI-LD system). + +>>> + + + +#### A.4.3.2 HTTP request + +**GET** [/ngsi-ld/v1/types/Vehicle]{.HTML-Variable} + +[Alternative with FQN: **GET** +[/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.4.3.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Response Body** + +```json +{ + "id": "http://example.org/vehicle/Vehicle", + "type": "EntityTypeInfo", + "typeName": "Vehicle", + "entityCount": 2, + "attributeDetails": [ + { + "id": "http://example.org/vehicle/brandName", + "type": "Attribute", + "attributeName": "brandName", + "attributeTypes": ["Property"] }, - "speed": { - "type": "Property", - "values": [ - [40, "2018-08-01T12:12:00Z"], - [60, "2018-08-01T12:14:00Z"], - [50, "2018-08-01T12:16:00Z"] - ] + { + "id": "http://example.org/vehicle/isParked", + "type": "Attribute", + "attributeName": "isParked", + "attributeTypes": ["Relationship"] }, - "@context": [ - "http://example.org/ngsi-ld/latest/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + { + "id": "https://uri.etsi.org/ngsi-ld/location", + "type": "Attribute", + "attributeName": "location", + "attributeTypes": ["GeoProperty"] + }, + { + "id": "http://example.org/vehicle/speed", + "type": "Attribute", + "attributeName": "speed", + "attributeTypes": ["Property"] + } + ] +} +``` + +## A.5 Attribute Examples + +### A.5.1 Retrieve available Attributes + +#### A.5.1.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back all attribute names for which entity instances are currently available +in the NGSI-LD system that have an attribute with the respective name. + +>>> + + + +#### A.5.1.2 HTTP request + +**GET** [/ngsi-ld/v1/attributes]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.5.1.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Response Body** + +```json +{ + "id": "urn:ngsi-ld:AttributeList:56534657", + "type": "AttributeList", + "attributeList": [ + "brandName", + "isParked", + "location", + "speed", + "http://example.org/parking/status" + ] +} +``` + + + +>>> [!note] NOTE: + +The attribute names that can be found in the provided +_`@context`_ are given as short names, the others as fully +qualified names (FQNs). + +>>> + + + +### A.5.2 Retrieve details of available Attributes + +#### A.5.2.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back the details of all attributes for which entity instances are currently +available in the NGSI-LD system to which an attribute with the respective +attribute name belongs. + +>>> + + + +#### A.5.2.2 HTTP request + +**GET** [/ngsi-ld/v1/attributes?details=true]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.5.2.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Response Body** + +```json +[ + { + "id": "http://example.org/vehicle/brandName", + "type": "Attribute", + "attributeName": "brandName", + "typeNames": ["Vehicle"] + }, + { + "id": "http://example.org/vehicle/isParked", + "type": "Attribute", + "attributeName": "isParked", + "typeNames": ["Vehicle"] + }, + { + "id": "https://uri.etsi.org/ngsi-ld/location", + "type": "Attribute", + "attributeName": "location", + "typeNames": [ + "Vehicle", + "OffStreetParking", + "http://example.org/parking/ParkingSpot" ] + }, + { + "id": "http://example.org/vehicle/speed", + "type": "Attribute", + "attributeName": "speed", + "typeNames": ["Vehicle"] + }, + { + "id": "http://example.org/parking/status", + "type": "Attribute", + "attributeName": "http://example.org/parking/status", + "typeNames": ["http://example.org/parking/ParkingSpot"] } ] ``` -Vehicle [B9211]{.HTML-Code} has already been within the Scope -[/Madrid/Centro]{.HTML-Code} before the beginning of the request interval, -whereas Vehicle [A8311]{.HTML-Code} 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. + + +>>> [!note] NOTE: + +The attribute name and all type names that can be found in the provided +_`@context`_ are given as short names, the others as Fully +Qualified Names (FQNs). The _`id`_ is always an FQN. + +>>> + + + +### A.5.3 Retrieve available Attribute information + +#### A.5.3.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back the details of the attribute named _`brandName`_ (for +which entity instances with an attribute of this name are currently available in +the NGSI-LD system). + +>>> + + + +#### A.5.3.2 HTTP request + +**GET** [/ngsi-ld/v1/attributes/brandName]{.HTML-Variable} + +\[ Alternative with FQN: **GET** +[/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]{.HTML-Variable} +\] + +**Request Headers** + +- [Accept: application/**json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +#### A.5.3.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**json**]{.HTML-Code} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%aggregatedContext.jsonld?core=1.9>;]{.HTML-Code + .indent} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} + +**Response Body** + +```json +{ + "id": "http://example.org/vehicle/brandName", + "type": "Attribute", + "attributeName": "brandName", + "attributeTypes": ["Property"], + "typeNames": ["Vehicle"], + "attributeCount": 2 +} +``` diff --git a/md/clause-6.md b/md/clause-6.md index b6172e13777a96729479d41a348c733e289fb1d0..add03aa23424dce82ad71a8297498d9e2fd1b6c6 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -753,13 +753,25 @@ notifications sent as a result of subscriptions with an In the HTTP Binding, if an HTTP Link header with a _`profile`_ parameter in accordance with IETF RFC 6906 [n.18], is found set to -[]{.HTML-Code} then +[https://uri.etsi.org/ngsi-ld/profile/<​version>]{.HTML-Code} 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 [n.1] ~clause 8.2.3) through amending the payload body and applying the fallbacks defined within [n.1] ~clause 9.5.3. + + +>>> [!tip] EXAMPLE: + +This example indicates that the payload conforms to the NGSI-LD 1.9 specification. + +[Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; rel="profile"]{.HTML-Code} + +>>> + + + ### 6.4.11 Limiting distributed operations The parameter described in this clause limits the execution of an operation to a