diff --git a/md/annex-c.md b/md/annex-c.md index 46b56cb6ab31d0b9a19528b9c5aff9856a6576f8..2281f75ecf44df3fd5c3122affb4748386578392 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: - <​https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld<; - rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json" +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"]{.HTML-Code} + +>>> + + + + -​ +>>> [!tip] EXAMPLE 2: -- **GET** -- Accept: application/ld+json -- Link: +**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, diff --git a/md/clause-13.md b/md/clause-13.md index e32ab5ad106b5ad29ddc6594934606c46775f6a8..cbe400503a9e669445e92c4076736194abcf9100 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 @@ -214,10 +218,29 @@ 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 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} + error if the identifier is not found. +- 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 identifier, serving it from its internal storage, if the _`@context`_ that @@ -226,10 +249,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