Merge branch 'feature/link-header-extension' into 'master'

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

{

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

{

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

{

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

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:

}

```

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

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:

<!-- prettier-ignore-start -->

>>> [!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

{

}

```

- 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}

>>>

<!-- prettier-ignore-end -->

<!-- prettier-ignore-start -->

​

>>> [!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

{

}

```

>>>

<!-- prettier-ignore-end -->

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

included by the wrapper _`@context`_ (not recommended) provided within

developer's requests.

<!-- prettier-ignore-start -->

>>> [!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]

>>>

<!-- prettier-ignore-end -->

## C.8 \@context processing clarifications

JSON-LD Specification [n.8] says that "If a term is redefined within a context,

### 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

- 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

  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