From 99bcfe96ff11f989675cc4b919ec1b143b8bad9a Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 12:00:52 +0100 Subject: [PATCH 1/6] Define _core_ parameter and explain the payload to be returned. --- md/clause-13.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/md/clause-13.md b/md/clause-13.md index e32ab5a..e14bb86 100644 --- a/md/clause-13.md +++ b/md/clause-13.md @@ -214,10 +214,23 @@ Figure: Serve \@context use case - A boolean [details]{.HTML-Variable} flag indicating that a JSON object representing metadata about the _`@context`_, instead of the full content, is requested (optional). +- A semantically versioned string [core]{.HTML-Variable} in the form + **major.minor**, conforming to a version of the NGSI-LD specification. When + present, a JSON-LD _`@context`_ holding both the user _`@context`_ URL and the + core _`@context`_ URL is returned (optional). ### 13.4.4 Behaviour -- If [details]{.HTML-Variable} is set to [false]{.HTML-Variable}, or +- if [details]{.HTML-Variable} is set to [true]{.HTML-Variable}, the broker + shall give back metadata about the _`@context`_ that corresponds to the + indicated local identifier. It shall give back [ResourceNotFound]{.HTML-Error} + error if the identifier is not found. +- if [core]{.HTML-Variable} is present, the broker shall return an _`@context`_ + in the form of an array of reference URLs (as defined in the JSON-LD + specification [n.8] section 3.1). The array shall hold two items - one URL + reference for the original location of the requested user _`@context`_, and + one URL for the location of the core _`@context`_. +- Otherwise, if [details]{.HTML-Variable} is set to [false]{.HTML-Variable}, or [details]{.HTML-Variable} is not present, the broker shall give back the full content of the _`@context`_ that corresponds to the indicated local identifier, serving it from its internal storage, if the _`@context`_ that @@ -226,10 +239,6 @@ Figure: Serve \@context use case back [OperationNotSupported]{.HTML-Error} error if it is of kind ["Cached"]{.HTML-Code}. It shall give back [ResourceNotFound]{.HTML-Error} if the identifier is not found. -- Otherwise, if [details]{.HTML-Variable} is set to [true]{.HTML-Variable}, the - broker shall give back metadata about the _`@context`_ that corresponds to the - indicated local identifier. It shall give back [ResourceNotFound]{.HTML-Error} - error if the identifier is not found. ### 13.4.5 Output data -- GitLab From 168434d95247e1bfa37f3ce768c5825ebbf8cb47 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 12:34:45 +0100 Subject: [PATCH 2/6] Add error condition --- md/clause-13.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/md/clause-13.md b/md/clause-13.md index e14bb86..3af94eb 100644 --- a/md/clause-13.md +++ b/md/clause-13.md @@ -225,11 +225,15 @@ Figure: Serve \@context use case shall give back metadata about the _`@context`_ that corresponds to the indicated local identifier. It shall give back [ResourceNotFound]{.HTML-Error} error if the identifier is not found. -- if [core]{.HTML-Variable} is present, the broker shall return an _`@context`_ - in the form of an array of reference URLs (as defined in the JSON-LD - specification [n.8] section 3.1). The array shall hold two items - one URL - reference for the original location of the requested user _`@context`_, and - one URL for the location of the core _`@context`_. +- if [core]{.HTML-Variable} is present, and it does not conform to a + semantically versioned string, a [BadRequest]{.HTML-Error} error shall be + returned. +- if [core]{.HTML-Variable} is present and it conforms to a semantically + versioned string, the broker shall return an _`@context`_ in the form of an + array of reference URLs (as defined in the JSON-LD specification [n.8] section + 3.1). The array shall hold two items - one URL reference for the original + location of the requested user _`@context`_, and one URL for the location of + the core _`@context`_. - Otherwise, if [details]{.HTML-Variable} is set to [false]{.HTML-Variable}, or [details]{.HTML-Variable} is not present, the broker shall give back the full content of the _`@context`_ that corresponds to the indicated local -- GitLab From bc60c39e5bde55353d7a667f0f234d2dcfbd6bcd Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 12:43:55 +0100 Subject: [PATCH 3/6] Update description. --- md/clause-13.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/md/clause-13.md b/md/clause-13.md index 3af94eb..37446cf 100644 --- a/md/clause-13.md +++ b/md/clause-13.md @@ -181,10 +181,14 @@ fields: ### 13.4.1 Description -With this operation a client can obtain the full content of a specific -_`@context`_ (only for _`@contexts`_ of kind ["Hosted"]{.HTML-Code} or -["ImplicitlyCreated"]{.HTML-Code}), which is currently stored in the broker's -internal storage, or its metadata (for all kinds of stored _`@contexts`_). +With this operation a client can obtain one of the following: + +- The full content of a specific _`@context`_ (only for _`@contexts`_ of kind + ["Hosted"]{.HTML-Code} or ["ImplicitlyCreated"]{.HTML-Code}), which is + currently stored in the broker's internal storage +- An _`@context`_ array holding a specified _`@context`_ URL and the core + _`@context`_ URL. +- metadata for all kinds of stored _`@context`_. ### 13.4.2 Use case diagram -- GitLab From d8d4bf5aab54867ee223c9618bcef9d8ce37fffb Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Fri, 31 Oct 2025 19:42:53 +0100 Subject: [PATCH 4/6] Extend examples. --- md/annex-c.md | 186 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 154 insertions(+), 32 deletions(-) diff --git a/md/annex-c.md b/md/annex-c.md index 46b56cb..0843993 100644 --- a/md/annex-c.md +++ b/md/annex-c.md @@ -1841,9 +1841,14 @@ and implementers the following examples illustrate this concept. The scenario starts with the creation of an Entity using a JSON-LD _`@context`_ as follows: -- **POST** -- Content-Type: application/ld+json -- Content-Length: 200 +**POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} + +**Request Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} +- [Content-Length: 200]{.HTML-Code} + +**Request Body** ```json { @@ -1910,11 +1915,18 @@ may be no longer known by the broker). It is also interesting to note that the _`@context`_ array of the response payload body contains, indeed, our header-supplied _`@context`_: -- **GET** -- Accept: application/ld+json -- Link: +**GET** +[/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} +- [Link: <​http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Response Body** ```json { @@ -1943,8 +1955,14 @@ payload body contains, indeed, our header-supplied _`@context`_: Another interesting case to note is the one when an _`@context`_ with no matching terms or no _`@context`_ at all is supplied. See the following example: -- **GET** -- Accept: application/ld+json +**GET** +[/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/ld+json]{.HTML-Code} + +**Response Body** ```json { @@ -1978,7 +1996,7 @@ JSON-LD response, as mandated by the specification). The JSON-LD Specification [n.8] states clearly that **only one HTTP Link header** with the link relationship -<​http://www.w3.org/ns/json-ld#context> is required to appear. Such +["http://www.w3.org/ns/json-ld#context"]{.HTML-Code} is required to appear. Such statement has implications in terms of providing the JSON-LD _`@context`_ when using the NGSI-LD API. The main implication is that if the _`@context`_ is a compound one, i.e. an _`@context`_ which references multiple individual @@ -1990,8 +2008,8 @@ with an example: Imagine that it is desired to create an Entity providing _`@context`_ terms which are defined in two different JSON-LD _`@context`_ resources: -- http://example.org/vehicle/v1/vehicle-context.jsonld -- https://schema.org +- _`http://example.org/vehicle/v1/vehicle-context.jsonld`_ +- _`https://schema.org`_ If a developer wants to reference these two _`@context`_ resources from a Link header, a wrapper _`@context`_ can be easily created as follows: @@ -2006,8 +2024,8 @@ header, a wrapper _`@context`_ can be easily created as follows: } ``` -As such wrapper \@context needs to be referenced from a Link header by using a -URI, then it will have to be hosted at some place on the Web. Usually, +As such wrapper _`@context`_ needs to be referenced from a Link header by using +a URI, then it will have to be hosted at some place on the Web. Usually, developers will host _`@context`_ using popular and simple solutions such as GitHub or GitLab pages. As a result, developers will be able to use _`@context`_ in queries or when using ["application/json"]{.HTML-Code} as main content type @@ -2019,15 +2037,25 @@ tools. However, it should be noted this is not necessary for NGSI-LD, as the Core _`@context`_ is always implicitly included. Then, using such wrapper _`@context`_, (in our example hosted at -https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), the developer -will be able to issue requests like: +_`https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld`_), the +developer will be able to issue requests like: + + + +>>> [!tip] EXAMPLE 1: + +**POST** [/ngsi-ld/v1/entities/]{.HTML-Variable} -- **POST** -- Content-Type: application/json -- Content-Length: 200 -- Link: +**Request Headers** + +- [Content-Type: application/json]{.HTML-Code} +- [Content-Length: 200]{.HTML-Code} +- [Link: <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +**Request Body** ```json { @@ -2045,21 +2073,45 @@ will be able to issue requests like: } ``` -- 201 Created -- Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1 -- Link: +With a response as shown: + +**Status Code:** 201 Created + +**Response Headers** + +- [Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1]{.HTML-Code} +- [Link: <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld<; - rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} -​ +>>> -- **GET** -- Accept: application/ld+json -- Link: + + + + +>>> [!tip] EXAMPLE 2: + +**GET** [/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1]{.HTML-Variable} + +**Request Headers** + +- Accept: [application/ld+json]{.HTML-Code} +- [Link: <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; - rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" -- 200 OK -- Content-Type: application/ld+json + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +With a response as shown: + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/ld+json]{.HTML-Code} + +**Response Body** ```json { @@ -2078,6 +2130,10 @@ will be able to issue requests like: } ``` +>>> + + + Observe that in this case the broker is responding with the same wrapper _`@context`_ in the Link header of the HTTP Response or within the JSON-LD response payload body (when MIME type accepted is @@ -2088,6 +2144,72 @@ _`@context`_ terms or when the Core _`@context`_ has not been previously included by the wrapper _`@context`_ (not recommended) provided within developer's requests. + + +>>> [!tip] EXAMPLE 3: + +**GET** [/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1]{.HTML-Variable} + +**Request Headers** + +- Accept: [application/json]{.HTML-Code} +- [Link: + <​http://example.org/vehicle/v1/vehicle-context.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +With a response as shown: + +**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:V1", + "type": "Vehicle", + "builtYear": { + "type": "Property", + "value": "2014" + }, + "speed": { + "type": "Property", + "value": 121, + "observedAt": "2017-07-29T12:05:02Z" + } +} +``` + + +Since the core _`@context`_ was omitted from the request, the Link header refers +to a [Context Broker]{.HTML-Keyboard} endpoint _`/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9`_ +which 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 supplies the missing core _`@context`_ but maintains that the response contains **only one HTTP Link +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] + +>>> + + + ## C.8 \@context processing clarifications JSON-LD Specification [n.8] says that "If a term is redefined within a context, -- GitLab From cce025bded5ff24da6d91cad846839843eadde9f Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Sat, 1 Nov 2025 10:28:44 +0100 Subject: [PATCH 5/6] Correct character --- md/annex-c.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/md/annex-c.md b/md/annex-c.md index 0843993..2281f75 100644 --- a/md/annex-c.md +++ b/md/annex-c.md @@ -2081,7 +2081,7 @@ With a response as shown: - [Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1]{.HTML-Code} - [Link: - <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld<; + <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"]{.HTML-Code} -- GitLab From 80a138dfd3d61f941e494a697f401e1c578a8683 Mon Sep 17 00:00:00 2001 From: Jason Fox Date: Tue, 11 Nov 2025 11:40:14 +0100 Subject: [PATCH 6/6] Amend behaviour --- md/clause-13.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/md/clause-13.md b/md/clause-13.md index 37446cf..cbe4005 100644 --- a/md/clause-13.md +++ b/md/clause-13.md @@ -225,6 +225,8 @@ Figure: Serve \@context use case ### 13.4.4 Behaviour +- if both [details]{.HTML-Variable} and [core]{.HTML-Variable} are present, a + [BadRequest]{.HTML-Error} error shall be returned. - if [details]{.HTML-Variable} is set to [true]{.HTML-Variable}, the broker shall give back metadata about the _`@context`_ that corresponds to the indicated local identifier. It shall give back [ResourceNotFound]{.HTML-Error} -- GitLab