Commit b091d6a8 authored by Giuseppe Tropea's avatar Giuseppe Tropea
Browse files

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

DATA(25)000164_NGSI-LD_Core_correct_links

See merge request !11
parents 0407a070 bf75f573
Loading
Loading
Loading
Loading
+20 −18
Original line number Original line Diff line number Diff line
@@ -1106,10 +1106,10 @@ level of the graph only.
Below is an example, where temporal evolution of the speed of the car is
Below is an example, where temporal evolution of the speed of the car is
provided by two different sources. As both may be relevant at the same time,
provided by two different sources. As both may be relevant at the same time,
there are two individual attribute instances for speed; each is identified by a
there are two individual attribute instances for speed; each is identified by a
_`datasetId`_ and both instances are represented in an array. The combination of an
_`datasetId`_ and both instances are represented in an array. The combination of
Attribute's _`datasetId`_ and the _`instanceId`_  associated to each value enables
an Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value
modification of a particular instance value without affecting instances from other
enables modification of a particular instance value without affecting instances
sources.
from other sources.


```json
```json
{
{
@@ -2168,7 +2168,7 @@ been compacted, as the Core _`@context`_ is always considered to be implicitly
present if not specified explicitly (and that is why it is included in the
present if not specified explicitly (and that is why it is included in the
JSON-LD response, as mandated by the specification).
JSON-LD response, as mandated by the specification).


## C.7 Link header utilization clarifications
## C.7 JSON-LD Link header utilization clarifications


The JSON-LD Specification [n.8] states clearly that **only one HTTP Link
The JSON-LD Specification [n.8] states clearly that **only one HTTP Link
header** with the link relationship
header** with the link relationship
@@ -2178,8 +2178,8 @@ 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
compound one, i.e. an _`@context`_ which references multiple individual
_`@context`_, served by resources behind different URIs, then a **wrapper**
_`@context`_, served by resources behind different URIs, then a **wrapper**
_`@context`_ has to be created and hosted. The final aim is that only one
_`@context`_ has to be created and hosted. The final aim is that only one
_`@context`_ is referenced from the JSON-LD Link header. This can be illustrated
_`@context`_ is referenced from the JSON-LD [Link]{.HTML-Code} header. This can
with an example:
be illustrated with an example:


Imagine that it is desired to create an Entity providing _`@context`_ terms
Imagine that it is desired to create an Entity providing _`@context`_ terms
which are defined in two different JSON-LD _`@context`_ resources:
which are defined in two different JSON-LD _`@context`_ resources:
@@ -2187,8 +2187,9 @@ which are defined in two different JSON-LD _`@context`_ resources:
- _`http://example.org/vehicle/v1/vehicle-context.jsonld`_
- _`http://example.org/vehicle/v1/vehicle-context.jsonld`_
- _`https://schema.org`_
- _`https://schema.org`_


If a developer wants to reference these two _`@context`_ resources from a Link
If a developer wants to reference these two _`@context`_ resources from a
header, a wrapper _`@context`_ can be easily created as follows:
JSON-LD [Link]{.HTML-Code} header, a wrapper _`@context`_ can be easily created
as follows:


```json
```json
{
{
@@ -2200,12 +2201,13 @@ header, a wrapper _`@context`_ can be easily created as follows:
}
}
```
```


As such wrapper _`@context`_ needs to be referenced from a Link header by using
As such wrapper _`@context`_ needs to be referenced from a JSON-LD
a URI, then it will have to be hosted at some place on the Web. Usually,
[Link]{.HTML-Code} header by using a URI, then it will have to be hosted at some
developers will host _`@context`_ using popular and simple solutions such as
place on the Web. Usually, developers will host _`@context`_ using popular and
GitHub or GitLab pages. As a result, developers will be able to use _`@context`_
simple solutions such as GitHub or GitLab pages. As a result, developers will be
in queries or when using ["application/json"]{.HTML-Code} as main content type
able to use _`@context`_ in queries or when using
managed by their applications.
["application/json"]{.HTML-Code} as main content type managed by their
applications.


It is a **good practice to include the Core** _`@context`_ in the wrapper
It is a **good practice to include the Core** _`@context`_ in the wrapper
_`@context`_ so it can be used, off-the-shelf, by external JSON-LD processing
_`@context`_ so it can be used, off-the-shelf, by external JSON-LD processing
@@ -2311,8 +2313,8 @@ With a response as shown:
<!-- prettier-ignore-end -->
<!-- prettier-ignore-end -->


Observe that in this case the broker is responding with the same wrapper
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
_`@context`_ in the JSON-LD [Link]{.HTML-Code} header of the HTTP Response or
response payload body (when MIME type accepted is
within the JSON-LD response payload body (when MIME type accepted is
["application/ld+json"]{.HTML-Code}). However, that could not be always the
["application/ld+json"]{.HTML-Code}). However, that could not be always the
case, as there could be situations where the broker could need to provide a
case, as there could be situations where the broker could need to provide a
wrapper _`@context`_ hosted by itself, for instance, when there are inline
wrapper _`@context`_ hosted by itself, for instance, when there are inline
@@ -2365,7 +2367,7 @@ With a response as shown:
```
```




Since the core _`@context`_ was omitted from the request, the Link header refers
Since the core _`@context`_ was omitted from the request, the JSON-LD [Link]{.HTML-Code} 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`_
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:
which returns the following JSON-LD _`@context`_ referencing two files:


+20 −15
Original line number Original line Diff line number Diff line
@@ -1646,20 +1646,23 @@ Figure: Retrieve Entity use case
  ["application/ld+json"]{.HTML-Code}, return a JSON-LD object representing the
  ["application/ld+json"]{.HTML-Code}, return a JSON-LD object representing the
  Entity as mandated by clause 5.2.6.4.1 and containing only the Attributes
  Entity as mandated by clause 5.2.6.4.1 and containing only the Attributes
  requested (if present).
  requested (if present).
  - If the Prefer Header [n.14] is set to
  - If the [Prefer]{.HTML-Code} Header [n.14] is set to
    ["ngsi-ld=&lt;&#8203;version&gt;"]{.HTML-Code} then the ContextBroker shall
    ["ngsi-ld=&lt;&#8203;version&gt;"]{.HTML-Code} then the ContextBroker shall
    endeavour to amend the JSON-LD object to conform to the specified version of
    endeavour to amend the JSON-LD object to conform to the specified version of
    the NGSI-LD specification as mandated in clause 9.5.3, and return a
    the NGSI-LD specification as mandated in clause 9.5.3, and return a
    Preference-Applied Header set to
    [Preference-Applied]{.HTML-Code} Header set to
    ["ngsi-ld=&lt;&#8203;conformant-version&gt;"]{.HTML-Code} in the response.
    ["ngsi-ld=&lt;&#8203;conformant-version&gt;"]{.HTML-Code} in the response.


- If the Accept Header is set to ["application/geo+json"]{.HTML-Code}, a GeoJSON
- If the [Accept]{.HTML-Code} Header is set to
  _Feature_ object representing the entity as mandated by clause 5.2.6.11.1 and
  ["application/geo+json"]{.HTML-Code}, a GeoJSON _Feature_ object representing
  containing only the Attributes requested (if present):
  the entity as mandated by clause 5.2.6.11.1 and containing only the Attributes
  - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then
  requested (if present):
    the _Feature_ object will also contain an _`@context`_ field.
  - If the [Prefer]{.HTML-Code} Header is omitted or set to
  - If the Prefer Header is set to ["body=json"]{.HTML-Code} the _`@context`_ is
    ["body=ld+json"]{.HTML-Code} then the _Feature_ object will also contain an
    set as a Link Header and removed from the Feature object.
    _`@context`_ field.
  - If the [Prefer]{.HTML-Code} Header is set to ["body=json"]{.HTML-Code} the
    _`@context`_ is set as a [Link]{.HTML-Code} Header and removed from the
    Feature object.


#### 10.4.2.5 Output data
#### 10.4.2.5 Output data


@@ -1973,21 +1976,23 @@ If the execution of the operation is limited to the local scope (see clause
  ["application/ld+json",]{.HTML-Code} a JSON-LD array is returned, representing
  ["application/ld+json",]{.HTML-Code} a JSON-LD array is returned, representing
  the Entities as mandated by clause 5.2.6.4.1 and containing only the
  the Entities as mandated by clause 5.2.6.4.1 and containing only the
  Attributes requested (if present).
  Attributes requested (if present).
  - If the Prefer Header [n.14] is set to
  - If the [Prefer]{.HTML-Code} Header [n.14] is set to
    ["ngsi-ld=&lt;&#8203;version&gt;"]{.HTML-Code} then the ContextBroker shall
    ["ngsi-ld=&lt;&#8203;version&gt;"]{.HTML-Code} then the ContextBroker shall
    endeavour to amend the elements of the JSON-LD array to conform to the
    endeavour to amend the elements of the JSON-LD array to conform to the
    specified version of the NGSI-LD specification as mandated in clause 9.5.3,
    specified version of the NGSI-LD specification as mandated in clause 9.5.3,
    and return a Preference-Applied Header set to
    and return a [Preference-Applied]{.HTML-Code} Header set to
    ["ngsi-ld=&lt;&#8203;conformant-version&gt;"]{.HTML-Code} in the response.
    ["ngsi-ld=&lt;&#8203;conformant-version&gt;"]{.HTML-Code} in the response.


- If the Accept Header is set to ["application/geo+json",]{.HTML-Code} the
- If the Accept Header is set to ["application/geo+json",]{.HTML-Code} the
  response shall be a GeoJSON _FeatureCollection_ as mandated by clause
  response shall be a GeoJSON _FeatureCollection_ as mandated by clause
  5.2.6.11.2, with each _Feature_ within the _FeatureCollection_ containing only
  5.2.6.11.2, with each _Feature_ within the _FeatureCollection_ containing only
  the Attributes requested (if present):
  the Attributes requested (if present):
  - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then
  - If the [Prefer]{.HTML-Code} Header is omitted or set to
    the _FeatureCollection_ will also contain an _`@context`_ field.
    ["body=ld+json"]{.HTML-Code} then the _FeatureCollection_ will also contain
  - If the Prefer Header is set to ["body=json]{.HTML-Code}" the _`@context`_ is
    an _`@context`_ field.
    sent as a Link Header and removed from the _FeatureCollection_ object.
  - If the [Prefer]{.HTML-Code} Header is set to ["body=json]{.HTML-Code}" the
    _`@context`_ is sent as a [Link]{.HTML-Code} Header and removed from the
    _FeatureCollection_ object.


#### 10.4.3.5 Output data
#### 10.4.3.5 Output data


+5 −5
Original line number Original line Diff line number Diff line
@@ -18,11 +18,11 @@ Consequently, the broker has no ability to cache _`@contexts`_ that arrive to it
as **embedded** parts within the NGSI-LD documents, since they are not uniquely
as **embedded** parts within the NGSI-LD documents, since they are not uniquely
(and implicitly) identified by any URL; [Context Brokers]{.HTML-Keyboard} only
(and implicitly) identified by any URL; [Context Brokers]{.HTML-Keyboard} only
cache _`@contexts`_ that are referred to by means of explicit URLs (either in
cache _`@contexts`_ that are referred to by means of explicit URLs (either in
the HTTP Link header or as URLs in the payload body). Thus, the **recommended
the HTTP [Link]{.HTML-Code} header or as URLs in the payload body). Thus, the
best-practice, in order to exploit caching, is that clients do not embed their
**recommended best-practice, in order to exploit caching, is that clients do not
user** _`@contexts`_ **into their NGSI-LD documents**; instead clients should
embed their user** _`@contexts`_ **into their NGSI-LD documents**; instead
explicitly host their user _`@contexts`_ at their premises, or use the broker's
clients should explicitly host their user _`@contexts`_ at their premises, or
capability to host user _`@contexts`_ on their behalf.
use the broker's capability to host user _`@contexts`_ on their behalf.


When an external _`@context`_ is stored, either explicitly upon a client's
When an external _`@context`_ is stored, either explicitly upon a client's
request or implicitly downloaded for caching purposes, the Context Broker
request or implicitly downloaded for caching purposes, the Context Broker
+4 −4
Original line number Original line Diff line number Diff line
@@ -3811,14 +3811,14 @@ following terms:
  mapping the Property name with its Property Identifier (URI).
  mapping the Property name with its Property Identifier (URI).
Whereas the Core NGSI-LD _`@context`_ contains JSON-LD Scoped Contexts, the user
Whereas the Core NGSI-LD _`@context`_ contains JSON-LD Scoped Contexts, the user
_`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8],
_`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8], Section
Clause+++root.3.2.1), as described in Clause+++clause-8+++8.2.4, because this
4.1.8), as described in Clause+++clause-8+++8.2.4, because this would enable
would enable overwriting terms defined in the Core NGSI-LD _`@context`_.
overwriting terms defined in the Core NGSI-LD _`@context`_.
Depending on the binding, the _`@context`_ may not just be provided embedded
Depending on the binding, the _`@context`_ may not just be provided embedded
with the rest of the JSON content, but there could be other options. For
with the rest of the JSON content, but there could be other options. For
example, in the HTTP binding, the _`@context`_ can be made available through a
example, in the HTTP binding, the _`@context`_ can be made available through a
Link header (see Clause+++clause-6+++6.2.4).
[Link]{.HTML-Code} header (see [n.8], Section 6.2).
#### 5.3.2.2 Entities Normalized
#### 5.3.2.2 Entities Normalized
+7 −6
Original line number Original line Diff line number Diff line
@@ -88,12 +88,13 @@ operations (Clause+++clause-10+++10.4.3), the _`@context`_ used to perform URI
expansion and compaction shall be the one provided by the request.
expansion and compaction shall be the one provided by the request.


In case of HTTP binding via GET (see [i.16] ~clause 7.2.3.1) of the "Query
In case of HTTP binding via GET (see [i.16] ~clause 7.2.3.1) of the "Query
Entities" operation, this means using the JSON-LD Link Header as described by
Entities" operation, this means using the JSON-LD [Link]{.HTML-Code} Header as
the JSON-LD specification [n.8], section 6.2. In case of HTTP binding via POST
described by the JSON-LD specification [n.8], section 6.2. In case of HTTP
(see [i.16] ~clause 7.12.3.1), of the "Query Entities" operation, this means
binding via POST (see [i.16] ~clause 7.12.3.1), of the "Query Entities"
giving the _`@context`_ either via Link Header or within the payload body,
operation, this means giving the _`@context`_ either via [Link]{.HTML-Code}
depending on the Content-Type Header being ["application/json"]{.HTML-Code} or
Header or within the payload body, depending on the Content-Type Header being
["application/ld+json"]{.HTML-Code}, respectively.
["application/json"]{.HTML-Code} or ["application/ld+json"]{.HTML-Code},
respectively.


It is important to warn users that updating a _`@context`_ could lead to
It is important to warn users that updating a _`@context`_ could lead to
behaviour that might be perceived as inconsistent. If, for instance, a fully
behaviour that might be perceived as inconsistent. If, for instance, a fully
Loading