From f1376bfc6c9cafa62bf21578b46cabaa59f17832 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 11:17:23 +0100 Subject: [PATCH 1/6] Draft Link Header Extension for HTTP Binding. --- md/clause-10.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/md/clause-10.md b/md/clause-10.md index db0bba5..1c1786a 100644 --- a/md/clause-10.md +++ b/md/clause-10.md @@ -214,6 +214,10 @@ Table: Serve \@contexts URL parameters +-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ | Name | Data Type | Cardinality | Remarks | +=================+=================+=================+======================================================================================+ +| core | String | 0..1 | A semantically versioned string in the form *major.minor*, which conforms to a | +| | | | version of the NGSI-LD specification. When present the endpoint returns an array | +| | | | consisting of the user _`@context`_ URL and the core _`@context`_ URL. | ++-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ | details | Boolean | 0..1 | Whether the content of the _`@context`_ or its metadata is requested. | +-----------------+-----------------+-----------------+--------------------------------------------------------------------------------------+ ::: @@ -240,9 +244,11 @@ Table: Serve \@context request body and possible responses | | | | | | | Response Body | Data Type | Cardinality | Response Codes | Remarks | | +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| | | | | If the parameter details are _`false`_ or missing, response body contains a JSON object that has a root node named _`@context`_, which represents a JSON-LD "local context". | +| | | | | If the parameter _`details`_ is _`false`_ or missing, response body contains a JSON object that has a root node named _`@context`_, which represents a JSON-LD "local context". | +| | | | | | +| | JSON Object | 1 | 200 OK | If the parameter _`core`_ is present response body contains a JSON object that has a root node named _`@context`_ holding an array of URLs matching to JSON-LD "local context" and core context. | | | | | | | -| | JSON Object | 1 | 200 OK | If the parameter details are _`true`_, response body contains a JSON object as defined in [n.1] ~clause 13.4.5, which metadata of a JSON-LD "local context". | +| | | | | If the parameter _`details`_ is _`true`_, response body contains a JSON object as defined in [n.1] ~clause 13.4.5, which metadata of a JSON-LD "local context". The _`core`_ if present is ignored. | | +---------------------------------------------+-------------+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | | | | It is used to indicate that the request or its content is incorrect, see clause 6.3.2. | | | | | | | -- GitLab From 4011b6b314749b06f16232877f1ce0e66649177d Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 13:03:13 +0100 Subject: [PATCH 2/6] Add missing example. --- md/clause-6.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/md/clause-6.md b/md/clause-6.md index e5dbf6e..b6172e1 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -151,6 +151,9 @@ this header (marking it as a link to a JSON-LD _`@context`_ ). The third and final parameter flags the MIME type of the linked resource (JSON-LD). + +[Link: <​http://json-ld.org/contexts/person.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} + >>> -- GitLab From 7cadfe8ba50a989498bd1dbfcd1ae549f24564ce Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 15:20:02 +0100 Subject: [PATCH 3/6] Formatting or request/response headers. --- md/annex-a.md | 328 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 234 insertions(+), 94 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index 8bda05c..19406f0 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -26,9 +26,13 @@ This example illustrates how to create a new Entity of type **POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} -Content-Type: application/ld+json +**Request Headers** -Content-Length: 927 +- [Content-Type: application/ld+json]{.HTML-Code} + +- [Content-Length: 927]{.HTML-Code} + +**Request Body** ```json { @@ -79,9 +83,11 @@ Content-Length: 927 ### A.2.3 HTTP response -201 Created +**Status Code:** 201 Created -Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567 +**Response Headers** + +- [Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4567]{.HTML-Code} ## A.3 Query Entities @@ -105,16 +111,24 @@ NGSI-LD Simplified Format. **GET** [/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} -Link: -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.3.3 HTTP response -200 OK +**Status Code:** 200 OK -Content-Type: application/ld+json +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} + +**Response Body** ```json [ @@ -151,20 +165,28 @@ Simplified Format. Limit the number of entities retrieved to 2. **GET** [/ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.4.3 HTTP response -200 OK +**Status Code:** 200 OK -Content-Type: application/ld+json +**Response Headers** -Link: -</ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=2>; -rel="next"; type="application/ld+json" +- [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} + +**Response Body** ```json [ @@ -226,16 +248,24 @@ _`brandName`_ attribute is omitted in the response. **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} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: <​http://example.org/ ngsi-ld + /latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.5.3 HTTP response #1 -200 OK +**Status Code:** 200 OK -Content-Type: application/ld+json +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} + +**Response Body** ```json [ @@ -272,16 +302,24 @@ Content-Type: application/ld+json **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} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: <​http://example.org/ ngsi-ld + /latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.5.5 HTTP response #2 -200 OK +**Status Code:** 200 OK -Content-Type: application/ld+json +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} + +**Response Body** ```json [ @@ -336,16 +374,24 @@ required. **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} -Accept: application/ld+json +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} ### A.6.3 HTTP response -200 OK +**Status Code:** 200 OK -Content-Type: application/ld+json +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} + +**Response Body** ```json [ @@ -387,19 +433,31 @@ the NGSI-LD system. **GET** [/ngsi-ld/v1/types]{.HTML-Variable} -Accept: application/json +**Request Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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.7.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/json]{.HTML-Code} -Content-Type: application/json +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +**Response Body** ```json { @@ -444,19 +502,29 @@ currently available in the NGSI-LD system. **GET** [/ngsi-ld/v1/types?details=true]{.HTML-Variable} -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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.8.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/json]{.HTML-Code} -Content-Type: application/json +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +**Response Body** ```json [ @@ -520,19 +588,29 @@ instances are currently available in the NGSI-LD system). [Alternative with FQN: **GET** [/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FVehicle]{.HTML-Variable} -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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.9.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/json]{.HTML-Code} -Content-Type: application/json +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +**Response Body** ```json { @@ -588,19 +666,29 @@ in the NGSI-LD system that have an attribute with the respective name. **GET** [/ngsi-ld/v1/attributes]{.HTML-Variable} -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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.10.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/json]{.HTML-Code} -Content-Type: application/json +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +**Response Body** ```json { @@ -648,19 +736,29 @@ attribute name belongs. **GET** [/ngsi-ld/v1/attributes?details=true]{.HTML-Variable} -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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.11.3 HTTP response -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/json]{.HTML-Code} -Content-Type: application/json +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +**Response Body** ```json [ @@ -737,19 +835,29 @@ the NGSI-LD system). [/ngsi-ld/v1/attributes/http%3A%2F%2Fexample.org%2Fvehicle%2FbrandName]{.HTML-Variable} \] -Accept: application/json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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 -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/json]{.HTML-Code} -Content-Type: application/json +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +**Response Body** ```json { @@ -786,16 +894,24 @@ strings in German. [/ngsi-ld/v1/entities/?type=Vehicle&attrs=marque&q=marque[en-GB]=="Vauxhall Viva"&format=**simplified**&lang=de]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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 -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -833,16 +949,24 @@ Give back the maximum and average _`speed`_ of Entities of type **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} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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 -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -888,16 +1012,24 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. **GET** [/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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 -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ @@ -1002,16 +1134,24 @@ been set before, e.g. on 1st of August 2018 at 11 AM. **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} -Accept: application/ld+json +**Request Headers** -Link: ; -rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +- [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 -200 OK +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} -Content-Type: application/ld+json +**Response Body** ```json [ -- GitLab From 5926fea927e767bf97a725948ce1d708526f7648 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 18:14:54 +0100 Subject: [PATCH 4/6] Expand examples. --- md/annex-a.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 159 insertions(+), 12 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index 19406f0..e7b082e 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -22,8 +22,11 @@ This example illustrates how to create a new Entity of type + ### A.2.2 HTTP request +#### A.2.2.1 Creation using a JSON-LD body and no Link header + **POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} **Request Headers** @@ -81,6 +84,79 @@ This example illustrates how to create a new Entity of type } ``` +#### A.2.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} + + + +>>> [!note] NOTE: + +The URL found within the Link header above only refers to the user + _`@context`_ since the addition of the core _`@context`_ can be implied. + +>>> + + + +**Request Body** + +```json +{ + "id": "urn:ngsi-ld:Vehicle:A4567", + "type": "Vehicle", + "brandName": { + "type": "Property", + "value": "Mercedes" + }, + "street": { + "type": "LanguageProperty", + "languageMap": { + "fr": "Grand Place", + "nl": "Grote Markt" + } + }, + "isParked": { + "type": "Relationship", + "objectType": "OffStreetParking", + "object": "urn:ngsi-ld:OffStreetParking:Downtown1", + "observedAt": "2017-07-29T12:00:04Z", + "providedBy": { + "type": "Relationship", + "object": "urn:ngsi-ld:Person:Bob" + } + }, + "category": { + "type": "VocabProperty", + "vocab": "non-commercial" + }, + "tyreTreadDepths": { + "type": "ListProperty", + "valueList": [300, 300, 120, 6], + "valueType": "Integer", + "unitCode": "MMT" + }, + "passengers": { + "type": "Relationship", + "objectType": "Person", + "object": ["urn:ngsi-ld:Person:Alice", "urn:ngsi-ld:Person:Bob"] + } +} +``` + + + ### A.2.3 HTTP response **Status Code:** 201 Created @@ -108,6 +184,8 @@ NGSI-LD Simplified Format. ### A.3.2 HTTP request +#### A.3.2.1 Query requesting a JSON-LD Response + **GET** [/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} @@ -116,12 +194,30 @@ NGSI-LD Simplified Format. - [Accept: application/ld+json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld> + <​http://example.org/ngsi-ld/latest/vehicle.jsonld> + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +#### A.3.2.2 Query requesting a JSON Response + +**GET** +[/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} + +**Request Headers** + +- [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} ### A.3.3 HTTP response +#### A.3.3.1 JSON-LD Response + +The JSON-LD response contains a JSON-LD body with _`@context`_ and returns no Link Header. + **Status Code:** 200 OK **Response Headers** @@ -144,6 +240,59 @@ NGSI-LD Simplified Format. ] ``` + +#### A.3.3.2 JSON Response + +The JSON only response contains a Link 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} + +**Response Body** + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "brandName": "Volvo" + } +] +``` + + + +>>> [!note] NOTE: + +The [Context Broker]{.HTML-Keyboard} endpoint _`/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9`_ +returns the following JSON-LD _`@context`_ referencing two files: + +```json +{ + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] +} +``` + + +This ensures that the response contains **only one HTTP Link +header** with the link relationship <​http://www.w3.org/ns/json-ld#context> +and therefore fully complies with the JSON-LD Specification [n.8] + +>>> + + + + ## A.4 Query Entities (pagination) ### A.4.1 Introduction @@ -170,7 +319,7 @@ Simplified Format. Limit the number of entities retrieved to 2. - [Accept: application/ld+json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -252,8 +401,7 @@ _`brandName`_ attribute is omitted in the response. - [Accept: application/ld+json]{.HTML-Code} -- [Link: <​http://example.org/ ngsi-ld - /latest/aggregatedContext.jsonld>; +- [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -306,8 +454,7 @@ _`brandName`_ attribute is omitted in the response. - [Accept: application/ld+json]{.HTML-Code} -- [Link: <​http://example.org/ ngsi-ld - /latest/aggregatedContext.jsonld>; +- [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -453,7 +600,7 @@ the NGSI-LD system. - [Content-Type: application/json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​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} @@ -520,7 +667,7 @@ currently available in the NGSI-LD system. - [Content-Type: application/json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​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} @@ -606,7 +753,7 @@ instances are currently available in the NGSI-LD system). - [Content-Type: application/json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​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} @@ -684,7 +831,7 @@ in the NGSI-LD system that have an attribute with the respective name. - [Content-Type: application/json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​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} @@ -754,7 +901,7 @@ attribute name belongs. - [Content-Type: application/json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​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} @@ -853,7 +1000,7 @@ the NGSI-LD system). - [Content-Type: application/json]{.HTML-Code} - [Link: - <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + <​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 9781f5663a98978cc1eacc88384d77bf7dd6a362 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 19:42:04 +0100 Subject: [PATCH 5/6] Prettifying --- md/annex-a.md | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index e7b082e..f3b983e 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -22,7 +22,6 @@ This example illustrates how to create a new Entity of type - ### A.2.2 HTTP request #### A.2.2.1 Creation using a JSON-LD body and no Link header @@ -90,8 +89,7 @@ This example illustrates how to create a new Entity of type **Request Headers** -- [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} @@ -155,8 +153,6 @@ The URL found within the Link header above only refers to the user } ``` - - ### A.2.3 HTTP response **Status Code:** 201 Created @@ -184,7 +180,7 @@ NGSI-LD Simplified Format. ### A.3.2 HTTP request -#### A.3.2.1 Query requesting a JSON-LD Response +#### A.3.2.1 Query requesting a JSON-LD Response **GET** [/ngsi-ld/v1/entities/?type=Vehicle&q=brandName!="Mercedes"&format=**simplified**]{.HTML-Variable} @@ -193,8 +189,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} @@ -207,8 +202,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} @@ -216,7 +210,8 @@ NGSI-LD Simplified Format. #### A.3.3.1 JSON-LD Response -The JSON-LD response contains a JSON-LD body with _`@context`_ and returns no Link Header. +The JSON-LD response contains a JSON-LD body with _`@context`_ and returns no +Link Header. **Status Code:** 200 OK @@ -240,10 +235,10 @@ The JSON-LD response contains a JSON-LD body with _`@context`_ and returns no Li ] ``` - #### A.3.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 Link Header and returns a JSON body without an +_`@context`_. **Status Code:** 200 OK @@ -285,14 +280,14 @@ returns the following JSON-LD _`@context`_ referencing two files: This ensures that the response contains **only one HTTP Link -header** with the link relationship <​http://www.w3.org/ns/json-ld#context> +header** with the link relationship +["http://www.w3.org/ns/json-ld#context"]{.HTML-Code} and therefore fully complies with the JSON-LD Specification [n.8] >>> - ## A.4 Query Entities (pagination) ### A.4.1 Introduction @@ -318,8 +313,7 @@ Simplified Format. Limit the number of entities retrieved to 2. - [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} @@ -401,7 +395,8 @@ _`brandName`_ attribute is omitted in the response. - [Accept: application/ld+json]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} @@ -454,7 +449,8 @@ _`brandName`_ attribute is omitted in the response. - [Accept: application/ld+json]{.HTML-Code} -- [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -- GitLab From 55e86f67cc3f83575bfaee671877d13c1eb74576 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Sat, 1 Nov 2025 10:53:10 +0100 Subject: [PATCH 6/6] Emphasise content type --- md/annex-a.md | 70 +++++++++++++++++++++++++-------------------------- 1 file changed, 34 insertions(+), 36 deletions(-) diff --git a/md/annex-a.md b/md/annex-a.md index f3b983e..6c1c980 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -30,7 +30,7 @@ This example illustrates how to create a new Entity of type **Request Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} - [Content-Length: 927]{.HTML-Code} @@ -93,7 +93,7 @@ This example illustrates how to create a new Entity of type rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -- [Content-Type: application/json]{.HTML-Code} +- [Content-Type: application/**json**]{.HTML-Code} - [Content-Length: 783]{.HTML-Code} @@ -187,7 +187,7 @@ NGSI-LD Simplified Format. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld> rel="http://www.w3.org/ns/json-ld#context"; @@ -200,7 +200,7 @@ NGSI-LD Simplified Format. **Request Headers** -- [Accept: application/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"; @@ -217,7 +217,7 @@ Link Header. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -244,7 +244,7 @@ _`@context`_. **Response Headers** -- [Content-Type: application/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%2Fvehicle.jsonld?core=1.9> rel="http://www.w3.org/ns/json-ld#context"; @@ -311,7 +311,7 @@ Simplified Format. Limit the number of entities retrieved to 2. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/vehicle.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; @@ -323,7 +323,7 @@ Simplified Format. Limit the number of entities retrieved to 2. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} - [Link: </ngsi-ld/v1/entities/?type=Vehicle&format=**simplified**&limit=2&offset=>; @@ -393,7 +393,7 @@ _`brandName`_ attribute is omitted in the response. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -406,7 +406,7 @@ _`brandName`_ attribute is omitted in the response. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -447,7 +447,7 @@ _`brandName`_ attribute is omitted in the response. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -460,7 +460,7 @@ _`brandName`_ attribute is omitted in the response. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -519,7 +519,7 @@ required. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -532,7 +532,7 @@ required. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -578,9 +578,7 @@ the NGSI-LD system. **Request Headers** -- [Content-Type: application/ld+json]{.HTML-Code} - -- [Accept: application/json]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -593,7 +591,7 @@ the NGSI-LD system. **Response Headers** -- [Content-Type: application/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> @@ -647,7 +645,7 @@ currently available in the NGSI-LD system. **Request Headers** -- [Accept: application/json]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -660,7 +658,7 @@ currently available in the NGSI-LD system. **Response Headers** -- [Content-Type: application/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> @@ -733,7 +731,7 @@ instances are currently available in the NGSI-LD system). **Request Headers** -- [Accept: application/json]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -746,7 +744,7 @@ instances are currently available in the NGSI-LD system). **Response Headers** -- [Content-Type: application/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> @@ -811,7 +809,7 @@ in the NGSI-LD system that have an attribute with the respective name. **Request Headers** -- [Accept: application/json]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -824,7 +822,7 @@ in the NGSI-LD system that have an attribute with the respective name. **Response Headers** -- [Content-Type: application/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> @@ -881,7 +879,7 @@ attribute name belongs. **Request Headers** -- [Accept: application/json]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -894,7 +892,7 @@ attribute name belongs. **Response Headers** -- [Content-Type: application/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> @@ -980,7 +978,7 @@ the NGSI-LD system). **Request Headers** -- [Accept: application/json]{.HTML-Code} +- [Accept: application/**json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -993,7 +991,7 @@ the NGSI-LD system). **Response Headers** -- [Content-Type: application/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> @@ -1039,7 +1037,7 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -1052,7 +1050,7 @@ Viva"&format=**simplified**&lang=de]{.HTML-Variable} **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -1094,7 +1092,7 @@ Give back the maximum and average _`speed`_ of Entities of type **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -1107,7 +1105,7 @@ Give back the maximum and average _`speed`_ of Entities of type **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -1157,7 +1155,7 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -1170,7 +1168,7 @@ within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** @@ -1279,7 +1277,7 @@ been set before, e.g. on 1st of August 2018 at 11 AM. **Request Headers** -- [Accept: application/ld+json]{.HTML-Code} +- [Accept: application/**ld+json**]{.HTML-Code} - [Link: <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; @@ -1292,7 +1290,7 @@ been set before, e.g. on 1st of August 2018 at 11 AM. **Response Headers** -- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Type: application/**ld+json**]{.HTML-Code} **Response Body** -- GitLab