From 74df8ba2a4a051a8f443c41f43ae48940586c921 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 12 Nov 2025 14:52:17 +0100 Subject: [PATCH 01/10] Reorder existing examples --- md/annex-a.md | 880 +++++++++++++++++++++++++------------------------- 1 file changed, 444 insertions(+), 436 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index 6c1c980..6a650c8 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,7 +85,7 @@ 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} @@ -153,7 +155,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 +163,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 +180,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} @@ -193,7 +195,7 @@ NGSI-LD Simplified Format. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -#### 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} @@ -206,9 +208,9 @@ NGSI-LD Simplified Format. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### 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. @@ -235,7 +237,7 @@ 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`_. @@ -288,9 +290,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 @@ -304,7 +306,7 @@ Simplified Format. Limit the number of entities retrieved to 2. -### A.4.2 HTTP request +#### A.2.3.2 HTTP request **GET** [/ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2]{.HTML-Variable} @@ -317,7 +319,7 @@ Simplified Format. Limit the number of entities retrieved to 2. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.4.3 HTTP response +#### A.2.3.3 HTTP response **Status Code:** 200 OK @@ -354,9 +356,186 @@ Simplified Format. Limit the number of entities retrieved to 2. ] ``` -## A.5 Temporal Query +### A.2.4 Query Entities (natural language filtering) + +#### A.2.4.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.2.4.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.2.4.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} + +**Response Body** + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "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" + ] + } +] +``` + +### A.2.5 Scope Queries + +#### A.2.5.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}. + +>>> + + + +#### A.2.5.2 HTTP request + +**GET** +[/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.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.2.5.3 HTTP response + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} + +**Response Body** + +```json +[ + { + "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": "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.5.1 Introduction +### A.3.1 Temporal Query + +#### A.3.1.1 Introduction @@ -386,7 +565,7 @@ _`brandName`_ attribute is omitted in the response. -### A.5.2 HTTP request #1 +#### A.3.1.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} @@ -400,7 +579,7 @@ _`brandName`_ attribute is omitted in the response. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.5.3 HTTP response #1 +#### A.3.1.3 HTTP response #1 **Status Code:** 200 OK @@ -440,7 +619,7 @@ _`brandName`_ attribute is omitted in the response. ] ``` -### A.5.4 HTTP request #2 +#### A.3.1.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} @@ -454,7 +633,7 @@ _`brandName`_ attribute is omitted in the response. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.5.5 HTTP response #2 +#### A.3.1.5 HTTP response #2 **Status Code:** 200 OK @@ -494,9 +673,9 @@ _`brandName`_ attribute is omitted in the response. ] ``` -## A.6 Temporal Query (simplified representation) +### A.3.2 Temporal Query (simplified representation) -### A.6.1 Introduction +#### A.3.2.1 Introduction @@ -512,7 +691,7 @@ required. -### A.6.2 HTTP request +#### A.3.2.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} @@ -526,7 +705,7 @@ required. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.6.3 HTTP response +#### A.3.2.3 HTTP response **Status Code:** 200 OK @@ -557,126 +736,289 @@ required. ] ``` -## A.7 Retrieve available Entity Types +### A.3.3 Temporal Query (aggregated representation) -### A.7.1 Introduction +#### A.3.3.1 Introduction >>> [!tip] EXAMPLE: -Give back all entity types for which entity instances are currently available in -the NGSI-LD system. +Give back the maximum and average _`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, aggregated by periods of 4 minutes. >>> -### A.7.2 HTTP request +#### A.3.3.2 HTTP request -**GET** [/ngsi-ld/v1/types]{.HTML-Variable} +**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} **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} -### A.7.3 HTTP response +#### A.3.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> - 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:EntityTypeList:34534657", - "type": "EntityTypeList", - "typeList": [ - "Vehicle", - "OffStreetParking", - "http://example.org/parking/ParkingSpot" - ] -} +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": { + "type": "Property", + "max": [ + [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], + [100, "2018-08-01T12:04:00Z", "2018-08-01T12:08:00Z"] + ], + "avg": [ + [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], + [90, "2018-08-01T12:04:00Z", "2018-08-01T12:08: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: - -All entity types that can be found in the provided _`@context`_ -are given as short names, the others as Fully Qualified Names (FQNs). - ->>> - - - -## A.8 Retrieve details of available Entity Types +### A.3.4 Temporal Scope Queries -### A.8.1 Introduction +#### A.3.4.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 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.8.2 HTTP request +#### A.3.4.2 HTTP request -**GET** [/ngsi-ld/v1/types?details=true]{.HTML-Variable} +**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} **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} -### A.8.3 HTTP response +#### A.3.4.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} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** ```json [ { - "id": "http://example.org/vehicle/Vehicle", - "type": "EntityType", - "typeName": "Vehicle", - "attributeNames": ["brandName", "isParked", "location", "speed"] - }, - { - "id": "http://example.org/parking/OffStreetParking", + "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": "urn:ngsi-ld:Vehicle:A8311", + "type": "Vehicle", + "scope": { + "type": "Property", + "values": [ + [["/Madrid/Centro", "/Company123/UnitA"], "2018-08-01T12:10:00Z"] + ] + }, + "speed": { + "type": "Property", + "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/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] +``` + +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.4.1 Retrieve available Entity Types + +#### A.4.1.1 Introduction + + + +>>> [!tip] EXAMPLE: + +Give back all entity types for which entity instances are currently available in +the NGSI-LD system. + +>>> + + + +#### A.4.1.2 HTTP request + +**GET** [/ngsi-ld/v1/types]{.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.4.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> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**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>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +#### 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> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**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": [ @@ -707,9 +1049,9 @@ Fully Qualified Names (FQNs). The _`id`_ is always an FQN. -## A.9 Retrieve available Entity Type information +### A.4.3 Retrieve available Entity Type information -### A.9.1 Introduction +#### A.4.3.1 Introduction @@ -722,7 +1064,7 @@ instances are currently available in the NGSI-LD system). -### A.9.2 HTTP request +#### A.4.3.2 HTTP request **GET** [/ngsi-ld/v1/types/Vehicle]{.HTML-Variable} @@ -738,7 +1080,7 @@ instances are currently available in the NGSI-LD system). rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.9.3 HTTP response +#### A.4.3.3 HTTP response **Status Code:** 200 OK @@ -788,9 +1130,11 @@ instances are currently available in the NGSI-LD system). } ``` -## A.10 Retrieve available Attributes +## A.5 Attribute Examples + +### A.5.1 Retrieve available Attributes -### A.10.1 Introduction +#### A.5.1.1 Introduction @@ -803,7 +1147,7 @@ in the NGSI-LD system that have an attribute with the respective name. -### A.10.2 HTTP request +#### A.5.1.2 HTTP request **GET** [/ngsi-ld/v1/attributes]{.HTML-Variable} @@ -816,7 +1160,7 @@ in the NGSI-LD system that have an attribute with the respective name. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.10.3 HTTP response +#### A.5.1.3 HTTP response **Status Code:** 200 OK @@ -857,9 +1201,9 @@ qualified names (FQNs). -## A.11 Retrieve details of available Attributes +### A.5.2 Retrieve details of available Attributes -### A.11.1 Introduction +#### A.5.2.1 Introduction @@ -873,7 +1217,7 @@ attribute name belongs. -### A.11.2 HTTP request +#### A.5.2.2 HTTP request **GET** [/ngsi-ld/v1/attributes?details=true]{.HTML-Variable} @@ -886,7 +1230,7 @@ attribute name belongs. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.11.3 HTTP response +#### A.5.2.3 HTTP response **Status Code:** 200 OK @@ -952,9 +1296,9 @@ Qualified Names (FQNs). The _`id`_ is always an FQN. -## A.12 Retrieve available Attribute information +### A.5.3 Retrieve available Attribute information -### A.12.1 Introduction +#### A.5.3.1 Introduction @@ -968,7 +1312,7 @@ the NGSI-LD system). -### A.12.2 HTTP request +#### A.5.3.2 HTTP request **GET** [/ngsi-ld/v1/attributes/brandName]{.HTML-Variable} @@ -985,7 +1329,7 @@ the NGSI-LD system). rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -### A.12.3 HTTP response +#### A.5.3.3 HTTP response **Status Code:** 200 OK @@ -1010,339 +1354,3 @@ the NGSI-LD system). "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} - -**Response Body** - -```json -[ - { - "id": "urn:ngsi-ld:Vehicle:A4567", - "type": "Vehicle", - "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" - ] - } -] -``` - -## A.14 Temporal Query (aggregated representation) - -### A.14.1 Introduction - - - ->>> [!tip] EXAMPLE: - -Give back the maximum and average _`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, aggregated by periods of 4 minutes. - ->>> - - - -### A.14.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} - -**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.14.3 HTTP response - -**Status Code:** 200 OK - -**Response Headers** - -- [Content-Type: application/**ld+json**]{.HTML-Code} - -**Response Body** - -```json -[ - { - "id": "urn:ngsi-ld:Vehicle:B9211", - "type": "Vehicle", - "speed": { - "type": "Property", - "max": [ - [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], - [100, "2018-08-01T12:04:00Z", "2018-08-01T12:08:00Z"] - ], - "avg": [ - [120, "2018-08-01T12:00:00Z", "2018-08-01T12:04:00Z"], - [90, "2018-08-01T12:04:00Z", "2018-08-01T12:08: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.15 Scope Queries - -### A.15.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}. - ->>> - - - -### A.15.2 HTTP request - -**GET** -[/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.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.15.3 HTTP response - -**Status Code:** 200 OK - -**Response Headers** - -- [Content-Type: application/**ld+json**]{.HTML-Code} - -**Response Body** - -```json -[ - { - "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": "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.16 Temporal Scope Queries - -### A.16.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. - ->>> - - - -### A.16.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} - -**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.16.3 HTTP response - -**Status Code:** 200 OK - -**Response Headers** - -- [Content-Type: application/**ld+json**]{.HTML-Code} - -**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": "urn:ngsi-ld:Vehicle:A8311", - "type": "Vehicle", - "scope": { - "type": "Property", - "values": [ - [["/Madrid/Centro", "/Company123/UnitA"], "2018-08-01T12:10:00Z"] - ] - }, - "speed": { - "type": "Property", - "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/vehicle.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" - ] - } -] -``` - -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. -- GitLab From 85d2df6b034a3effc39a30572acc5175f65b7a2a Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 12 Nov 2025 16:00:03 +0100 Subject: [PATCH 02/10] Add preference Example --- md/annex-a.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 169 insertions(+), 12 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index 6a650c8..e168bd0 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -36,6 +36,23 @@ This example illustrates how to create a new Entity of type - [Content-Length: 927]{.HTML-Code} +**Optional Request Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>; + rel="**profile**"]{.HTML-Code} + + + +>>> [!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. + +>>> + + + + **Request Body** ```json @@ -91,21 +108,29 @@ This example illustrates how to create a new Entity of type **Request Headers** +- [Content-Type: application/**json**]{.HTML-Code} + +- [Content-Length: 783]{.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} -- [Content-Type: application/**json**]{.HTML-Code} +**Optional Request Header** -- [Content-Length: 783]{.HTML-Code} +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>; + rel="**profile**"]{.HTML-Code} >>> [!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. +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. + >>> @@ -213,7 +238,7 @@ NGSI-LD Simplified Format. ##### 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 @@ -221,6 +246,11 @@ Link Header. - [Content-Type: application/**ld+json**]{.HTML-Code} +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; + rel="profile"]{.HTML-Code} + **Response Body** ```json @@ -239,7 +269,7 @@ Link Header. ##### A.2.2.3.2 JSON Response -The JSON only response contains a Link Header and returns a JSON body without an +The JSON only response contains a json-ld [Link]{.HTML-Code} header and returns a JSON body without an _`@context`_. **Status Code:** 200 OK @@ -252,6 +282,11 @@ _`@context`_. 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>; + rel="profile"]{.HTML-Code} + **Response Body** ```json @@ -300,7 +335,8 @@ 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 >>> @@ -309,7 +345,7 @@ Simplified Format. Limit the number of entities retrieved to 2. #### 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** @@ -328,8 +364,34 @@ Simplified Format. Limit the number of entities retrieved to 2. - [Content-Type: application/**ld+json**]{.HTML-Code} - [Link: - </ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=>; - rel="next"; type="application/ld+json"]{.HTML-Code} + </ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=0>; + rel="**previous**"; type="application/ld+json"]{.HTML-Code} + +- [Link: + </ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=4>; + rel="**next**"; type="application/ld+json"]{.HTML-Code} + +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>; + rel="**profile**"]{.HTML-Code} + + + +>>> [!note] NOTE: + +The URL found within the _`previous`_ [Link]{.HTML-Code} header shows the path to the previous two Entities +in the list + +The URL found within the _`next`_ [Link]{.HTML-Code} header shows the path to the next two Entities +in the list + +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 Body** @@ -370,6 +432,8 @@ 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_. + >>> @@ -397,6 +461,11 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} - [Content-Type: application/**ld+json**]{.HTML-Code} +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; + rel="profile"]{.HTML-Code} + **Response Body** ```json @@ -413,7 +482,8 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} ] ``` -### A.2.5 Scope Queries + +### A.2.5 Query Entities (preference) #### A.2.5.1 Introduction @@ -421,6 +491,88 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} >>> [!tip] EXAMPLE: +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.2.5.2 HTTP request + +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&attrs=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} + +#### A.2.5.3 HTTP response + +**Status Code:** 203 Non-Authoritative Information + +**Response Headers** + +- [Preference-Applied: ngsi-ld=**1.3**]{.HTML-Code} + +- [Content-Type: application/**json**]{.HTML-Code} + +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.3>; + rel="profile"]{.HTML-Code} + +**Response Body** + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "marque": { + "type": "Property", + "value": { + "en-gb": "Vauxhall Viva", + "de": "Opel Karl" + } + } + } +] +``` + + + + +>>> [!note] NOTE: + +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 indicates that a change has occurred. + +>>> + + + + +### A.2.6 Scope Queries + +#### A.2.6.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}. @@ -428,7 +580,7 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. -#### A.2.5.2 HTTP request +#### A.2.6.2 HTTP request **GET** [/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable} @@ -442,7 +594,7 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -#### A.2.5.3 HTTP response +#### A.2.6.3 HTTP response **Status Code:** 200 OK @@ -450,6 +602,11 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. - [Content-Type: application/**ld+json**]{.HTML-Code} +**Optional Response Header** + +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; + rel="profile"]{.HTML-Code} + **Response Body** ```json -- GitLab From c8333b01a0eddface67a1401be050651aaea154b Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 12 Nov 2025 16:35:40 +0100 Subject: [PATCH 03/10] Add example directly in clause --- md/clause-6.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/md/clause-6.md b/md/clause-6.md index b6172e1..add03aa 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 -- GitLab From 7ad92406a7ed18c6b237133c6baa58ec3cd4062a Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 12 Nov 2025 19:12:59 +0100 Subject: [PATCH 04/10] Use pick in preference to attrs --- md/annex-a.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index e168bd0..c225096 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -441,7 +441,7 @@ Note that the _`marque`_ attribute had been created using a _LanguageProperty_. #### A.2.4.2 HTTP request **GET** -[/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]=="Vauxhall +[/ngsi-ld/v1/entities/?type=Vehicle&pick=id,type,marque&q=marque[en-GB]=="Vauxhall Viva"&format=**simplified**&lang=de]{.HTML-Variable} **Request Headers** @@ -505,7 +505,7 @@ Note that the _`marque`_ attribute had been previously created using a _Language #### A.2.5.2 HTTP request **GET** -[/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&format=**normalized**]{.HTML-Variable} +[/ngsi-ld/v1/entities/?type=Vehicle&pick=id,type,marque&format=**normalized**]{.HTML-Variable} **Request Headers** @@ -725,7 +725,7 @@ _`brandName`_ attribute is omitted in the response. #### A.3.1.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} +[/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** @@ -779,7 +779,7 @@ _`brandName`_ attribute is omitted in the response. #### A.3.1.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} +[/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** @@ -851,7 +851,7 @@ required. #### A.3.2.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} +[/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** @@ -913,7 +913,7 @@ Give back the maximum and average _`speed`_ of Entities of type #### 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** @@ -980,7 +980,7 @@ been set before, e.g. on 1st of August 2018 at 11 AM. #### A.3.4.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} +[/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** -- GitLab From 90cfbba905dbb5cc2cc679bb3bcbb2c0e061f1d9 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 12 Nov 2025 21:51:42 +0100 Subject: [PATCH 05/10] Add link header --- md/annex-a.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/md/annex-a.md b/md/annex-a.md index c225096..fffe4fa 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -528,6 +528,11 @@ Note that the _`marque`_ attribute had been previously created using a _Language - [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.3**> + 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.3>; -- GitLab From 88626847594f85c298af4d69385a8baac09c6cd8 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Wed, 12 Nov 2025 22:08:41 +0100 Subject: [PATCH 06/10] Add missing semi-colons --- md/annex-a.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index fffe4fa..41c0c22 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -112,7 +112,7 @@ of this request conforms to the NGSI-LD 1.9 specification. - [Content-Length: 783]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -216,7 +216,7 @@ NGSI-LD Simplified Format. - [Accept: application/**ld+json**]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -229,7 +229,7 @@ NGSI-LD Simplified Format. - [Accept: application/**json**]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> +- [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -278,7 +278,7 @@ _`@context`_. - [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> + <​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} @@ -524,18 +524,18 @@ Note that the _`marque`_ attribute had been previously created using a _Language **Response Headers** -- [Preference-Applied: ngsi-ld=**1.3**]{.HTML-Code} - - [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.3**> + <​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"]{.HTML-Code} **Optional Response Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.3>; +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.3**>; rel="profile"]{.HTML-Code} **Response Body** @@ -1098,7 +1098,7 @@ the NGSI-LD system. - [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> + <​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} @@ -1165,7 +1165,7 @@ currently available in the NGSI-LD system. - [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> + <​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} @@ -1251,7 +1251,7 @@ instances are currently available in the NGSI-LD system). - [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> + <​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} @@ -1331,7 +1331,7 @@ in the NGSI-LD system that have an attribute with the respective name. - [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> + <​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} @@ -1401,7 +1401,7 @@ attribute name belongs. - [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> + <​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} @@ -1500,7 +1500,7 @@ the NGSI-LD system). - [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> + <​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} -- GitLab From 3fa0222d2dfbd901d8db273f7e85dab55eb27369 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Thu, 13 Nov 2025 07:48:44 +0100 Subject: [PATCH 07/10] Indent Link headers across multiple lines using CSS. --- md/annex-a.md | 323 +++++++++++++++++++++++++++++++------------------- 1 file changed, 201 insertions(+), 122 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index 41c0c22..431dd29 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -38,8 +38,11 @@ This example illustrates how to create a new Entity of type **Optional Request Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>; - rel="**profile**"]{.HTML-Code} +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code + .indent} + + [rel="**profile**"]{.HTML-Code .run-on} @@ -52,7 +55,6 @@ of this request conforms to the NGSI-LD 1.9 specification. - **Request Body** ```json @@ -112,14 +114,20 @@ of this request conforms to the NGSI-LD 1.9 specification. - [Content-Length: 783]{.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} **Optional Request Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>; - rel="**profile**"]{.HTML-Code} +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code + .indent} + + [rel="**profile**"]{.HTML-Code .run-on} @@ -216,9 +224,12 @@ 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.2.2.2.2 Query requesting a JSON Response @@ -229,9 +240,12 @@ 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.2.2.3 HTTP response @@ -248,8 +262,10 @@ json-ld [Link]{.HTML-Code} Header. **Optional Response Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; - rel="profile"]{.HTML-Code} +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** @@ -269,23 +285,28 @@ json-ld [Link]{.HTML-Code} Header. ##### A.2.2.3.2 JSON Response -The JSON only response contains a json-ld [Link]{.HTML-Code} 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>; - rel="profile"]{.HTML-Code} +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** @@ -349,11 +370,14 @@ the third Entity **Request Headers** -- [Accept: application/**ld+json**]{.HTML-Code} +- [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.2.3.3 HTTP response @@ -361,25 +385,42 @@ the third Entity **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=0>; - rel="**previous**"; 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} - [Link: - </ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=4>; - rel="**next**"; type="application/ld+json"]{.HTML-Code} + <​http://**<​context-broker>**/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=0>;]{.HTML-Code + .indent} + + [rel="**previous**"]{.HTML-Code .run-on} + +- [Link: + <​http://**<​context-broker>**/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=4>;]{.HTML-Code + .indent} + + [rel="**next**"]{.HTML-Code .run-on} **Optional Response Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>; - rel="**profile**"]{.HTML-Code} +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code + .indent} + + [rel="**profile**"]{.HTML-Code .run-on} >>> [!note] NOTE: +The URL found within the _`json-ld`_ [Link]{.HTML-Code} header above refers to the +combination of core and user @contexts. + The URL found within the _`previous`_ [Link]{.HTML-Code} header shows the path to the previous two Entities in the list @@ -400,20 +441,12 @@ of this response conforms to the NGSI-LD 1.9 specification. { "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" - ] + "brandName": "Volvo" }, { "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" - ] + "brandName": "Mercedes" } ] ``` @@ -449,9 +482,11 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} - [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.2.4.3 HTTP response @@ -463,8 +498,10 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} **Optional Response Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; - rel="profile"]{.HTML-Code} +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** @@ -482,7 +519,6 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} ] ``` - ### A.2.5 Query Entities (preference) #### A.2.5.1 Introduction @@ -514,9 +550,11 @@ Note that the _`marque`_ attribute had been previously created using a _Language - [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} + + [rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code .run-on} #### A.2.5.3 HTTP response @@ -529,14 +567,19 @@ Note that the _`marque`_ attribute had been previously created using a _Language - [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.3**>; - 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**>; - rel="profile"]{.HTML-Code} +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.3**>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** @@ -546,30 +589,28 @@ Note that the _`marque`_ attribute had been previously created using a _Language "id": "urn:ngsi-ld:Vehicle:A4567", "type": "Vehicle", "marque": { - "type": "Property", - "value": { - "en-gb": "Vauxhall Viva", - "de": "Opel Karl" - } + "type": "Property", + "value": { + "en-gb": "Vauxhall Viva", + "de": "Opel Karl" } + } } ] ``` - >>> [!note] NOTE: 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 indicates that a change has occurred. +and [Preference-Applied]{.HTML-Code} header indicate that a change has occurred. >>> - ### A.2.6 Scope Queries #### A.2.6.1 Introduction @@ -595,9 +636,11 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.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.2.6.3 HTTP response @@ -609,8 +652,10 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. **Optional Response Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>; - rel="profile"]{.HTML-Code} +- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code + .indent} + + [rel="profile"]{.HTML-Code .run-on} **Response Body** @@ -737,9 +782,11 @@ _`brandName`_ attribute is omitted in the response. - [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.3.1.3 HTTP response #1 @@ -791,9 +838,11 @@ _`brandName`_ attribute is omitted in the response. - [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.3.1.5 HTTP response #2 @@ -863,9 +912,11 @@ required. - [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.3.2.3 HTTP response @@ -925,9 +976,11 @@ Give back the maximum and average _`speed`_ of Entities of type - [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.3.3.3 HTTP response @@ -992,9 +1045,11 @@ been set before, e.g. on 1st of August 2018 at 11 AM. - [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.3.4.3 HTTP response @@ -1085,9 +1140,11 @@ the NGSI-LD system. - [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.4.1.3 HTTP response @@ -1098,9 +1155,11 @@ the NGSI-LD system. - [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} + <​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** @@ -1152,9 +1211,11 @@ currently available in the NGSI-LD system. - [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.4.2.3 HTTP response @@ -1165,9 +1226,11 @@ currently available in the NGSI-LD system. - [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} + <​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** @@ -1238,9 +1301,11 @@ instances are currently available in the NGSI-LD system). - [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.4.3.3 HTTP response @@ -1251,9 +1316,11 @@ instances are currently available in the NGSI-LD system). - [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} + <​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** @@ -1318,9 +1385,11 @@ in the NGSI-LD system that have an attribute with the respective name. - [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.5.1.3 HTTP response @@ -1331,9 +1400,11 @@ in the NGSI-LD system that have an attribute with the respective name. - [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} + <​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** @@ -1388,9 +1459,11 @@ attribute name belongs. - [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.5.2.3 HTTP response @@ -1401,9 +1474,11 @@ attribute name belongs. - [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} + <​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** @@ -1487,9 +1562,11 @@ the NGSI-LD system). - [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.5.3.3 HTTP response @@ -1500,9 +1577,11 @@ the NGSI-LD system). - [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} + <​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** -- GitLab From 585bef247444f4063f9641a57ab2bbf61954d204 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Thu, 13 Nov 2025 14:36:56 +0100 Subject: [PATCH 08/10] Move profile --- md/annex-a.md | 49 +++++++++++++++---------------------------------- 1 file changed, 15 insertions(+), 34 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index 431dd29..e9e5122 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -36,25 +36,6 @@ This example illustrates how to create a new Entity of type - [Content-Length: 927]{.HTML-Code} -**Optional Request 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. - ->>> - - - **Request Body** ```json @@ -121,24 +102,11 @@ of this request conforms to the NGSI-LD 1.9 specification. [rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code .run-on} -**Optional Request Header** - -- [Link: - <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code - .indent} - - [rel="**profile**"]{.HTML-Code .run-on} - - - >>> [!note] NOTE: 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. -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. - >>> @@ -262,10 +230,23 @@ json-ld [Link]{.HTML-Code} Header. **Optional Response Header** -- [Link: <​https://uri.etsi.org/ngsi-ld/profile/1.9>;]{.HTML-Code +- [Link: + <​https://uri.etsi.org/ngsi-ld/profile/**1.9**>;]{.HTML-Code .indent} - [rel="profile"]{.HTML-Code .run-on} + [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** -- GitLab From 9f672872a160f273d4a8d3a2fe6c4d14d64a9a3c Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Thu, 13 Nov 2025 14:42:54 +0100 Subject: [PATCH 09/10] Correct name --- md/annex-a.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index e9e5122..3e22d58 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -379,7 +379,7 @@ the third Entity <​http://**<​context-broker>**/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=0>;]{.HTML-Code .indent} - [rel="**previous**"]{.HTML-Code .run-on} + [rel="**prev**"]{.HTML-Code .run-on} - [Link: <​http://**<​context-broker>**/ngsi-ld/v1/entities/?type=Vehicle&format=simplified&limit=2&offset=4>;]{.HTML-Code @@ -402,7 +402,7 @@ the third Entity The URL found within the _`json-ld`_ [Link]{.HTML-Code} header above refers to the combination of core and user @contexts. -The URL found within the _`previous`_ [Link]{.HTML-Code} header shows the path to the previous two Entities +The URL found within the _`prev`_ [Link]{.HTML-Code} header shows the path to the previous two Entities in the list The URL found within the _`next`_ [Link]{.HTML-Code} header shows the path to the next two Entities -- GitLab From 8f4228c6cc51f41a5832cac5ce3a7e68c82bb040 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Mon, 24 Nov 2025 12:26:24 +0100 Subject: [PATCH 10/10] Amend Context --- md/annex-a.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/md/annex-a.md b/md/annex-a.md index 3e22d58..b581c46 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -617,7 +617,7 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. - [Accept: application/**ld+json**]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>;]{.HTML-Code + <​http://example.org/ngsi-ld/latest/parking.jsonld>;]{.HTML-Code .indent} [rel="http://www.w3.org/ns/json-ld#context"; -- GitLab