Loading md/annex-c.md +20 −18 Original line number Diff line number Diff line Loading @@ -1106,10 +1106,10 @@ level of the graph only. 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, 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 Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value enables modification of a particular instance value without affecting instances from other sources. _`datasetId`_ and both instances are represented in an array. The combination of an Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value enables modification of a particular instance value without affecting instances from other sources. ```json { Loading Loading @@ -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 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 header** with the link relationship Loading @@ -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 _`@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`_ is referenced from the JSON-LD Link header. This can be illustrated with an example: _`@context`_ is referenced from the JSON-LD [Link]{.HTML-Code} header. This can be illustrated 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: Loading @@ -2187,8 +2187,9 @@ which are defined in two different JSON-LD _`@context`_ resources: - _`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: If a developer wants to reference these two _`@context`_ resources from a JSON-LD [Link]{.HTML-Code} header, a wrapper _`@context`_ can be easily created as follows: ```json { Loading @@ -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 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 managed by their applications. As such wrapper _`@context`_ needs to be referenced from a JSON-LD [Link]{.HTML-Code} 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 managed by their applications. 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 Loading Loading @@ -2311,8 +2313,8 @@ With a response as shown: <!-- 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 _`@context`_ in the JSON-LD [Link]{.HTML-Code} header of the HTTP Response or within the JSON-LD response payload body (when MIME type accepted is ["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 wrapper _`@context`_ hosted by itself, for instance, when there are inline Loading Loading @@ -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`_ which returns the following JSON-LD _`@context`_ referencing two files: Loading md/clause-10.md +20 −15 Original line number Diff line number Diff line Loading @@ -1646,20 +1646,23 @@ Figure: Retrieve Entity use case ["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 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=<​version>"]{.HTML-Code} then the ContextBroker shall 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 Preference-Applied Header set to [Preference-Applied]{.HTML-Code} Header set to ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. - If the Accept Header is set to ["application/geo+json"]{.HTML-Code}, a GeoJSON _Feature_ object representing the entity as mandated by clause 5.2.6.11.1 and containing only the Attributes requested (if present): - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _Feature_ object will also contain an _`@context`_ field. - If the Prefer Header is set to ["body=json"]{.HTML-Code} the _`@context`_ is set as a Link Header and removed from the Feature object. - If the [Accept]{.HTML-Code} Header is set to ["application/geo+json"]{.HTML-Code}, a GeoJSON _Feature_ object representing the entity as mandated by clause 5.2.6.11.1 and containing only the Attributes requested (if present): - If the [Prefer]{.HTML-Code} Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _Feature_ object will also contain an _`@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 Loading Loading @@ -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 the Entities as mandated by clause 5.2.6.4.1 and containing only the 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=<​version>"]{.HTML-Code} then the ContextBroker shall 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, and return a Preference-Applied Header set to and return a [Preference-Applied]{.HTML-Code} Header set to ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. - If the Accept Header is set to ["application/geo+json",]{.HTML-Code} the response shall be a GeoJSON _FeatureCollection_ as mandated by clause 5.2.6.11.2, with each _Feature_ within the _FeatureCollection_ containing only the Attributes requested (if present): - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _FeatureCollection_ will also contain an _`@context`_ field. - If the Prefer Header is set to ["body=json]{.HTML-Code}" the _`@context`_ is sent as a Link Header and removed from the _FeatureCollection_ object. - If the [Prefer]{.HTML-Code} Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _FeatureCollection_ will also contain an _`@context`_ field. - 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 Loading md/clause-13.md +5 −5 Original line number Diff line number Diff line Loading @@ -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 (and implicitly) identified by any URL; [Context Brokers]{.HTML-Keyboard} only 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 best-practice, in order to exploit caching, is that clients do not embed their user** _`@contexts`_ **into their NGSI-LD documents**; instead clients should explicitly host their user _`@contexts`_ at their premises, or use the broker's capability to host user _`@contexts`_ on their behalf. the HTTP [Link]{.HTML-Code} header or as URLs in the payload body). Thus, the **recommended best-practice, in order to exploit caching, is that clients do not embed their user** _`@contexts`_ **into their NGSI-LD documents**; instead clients should explicitly host their user _`@contexts`_ at their premises, or use the broker's capability to host user _`@contexts`_ on their behalf. When an external _`@context`_ is stored, either explicitly upon a client's request or implicitly downloaded for caching purposes, the Context Broker Loading md/clause-5.md +4 −4 Original line number Diff line number Diff line Loading @@ -3811,14 +3811,14 @@ following terms: mapping the Property name with its Property Identifier (URI). Whereas the Core NGSI-LD _`@context`_ contains JSON-LD Scoped Contexts, the user _`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8], Clause+++root.3.2.1), as described in Clause+++clause-8+++8.2.4, because this would enable overwriting terms defined in the Core NGSI-LD _`@context`_. _`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8], Section 4.1.8), as described in Clause+++clause-8+++8.2.4, because this would enable overwriting terms defined in the Core NGSI-LD _`@context`_. 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 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 md/clause-8.md +7 −6 Original line number Diff line number Diff line Loading @@ -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. 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 the JSON-LD specification [n.8], section 6.2. In case of HTTP binding via POST (see [i.16] ~clause 7.12.3.1), of the "Query Entities" operation, this means giving the _`@context`_ either via Link Header or within the payload body, depending on the Content-Type Header being ["application/json"]{.HTML-Code} or ["application/ld+json"]{.HTML-Code}, respectively. Entities" operation, this means using the JSON-LD [Link]{.HTML-Code} Header as described by the JSON-LD specification [n.8], section 6.2. In case of HTTP binding via POST (see [i.16] ~clause 7.12.3.1), of the "Query Entities" operation, this means giving the _`@context`_ either via [Link]{.HTML-Code} Header or within the payload body, depending on the Content-Type Header being ["application/json"]{.HTML-Code} or ["application/ld+json"]{.HTML-Code}, respectively. 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 Loading Loading
md/annex-c.md +20 −18 Original line number Diff line number Diff line Loading @@ -1106,10 +1106,10 @@ level of the graph only. 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, 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 Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value enables modification of a particular instance value without affecting instances from other sources. _`datasetId`_ and both instances are represented in an array. The combination of an Attribute's _`datasetId`_ and the _`instanceId`_ associated to each value enables modification of a particular instance value without affecting instances from other sources. ```json { Loading Loading @@ -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 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 header** with the link relationship Loading @@ -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 _`@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`_ is referenced from the JSON-LD Link header. This can be illustrated with an example: _`@context`_ is referenced from the JSON-LD [Link]{.HTML-Code} header. This can be illustrated 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: Loading @@ -2187,8 +2187,9 @@ which are defined in two different JSON-LD _`@context`_ resources: - _`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: If a developer wants to reference these two _`@context`_ resources from a JSON-LD [Link]{.HTML-Code} header, a wrapper _`@context`_ can be easily created as follows: ```json { Loading @@ -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 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 managed by their applications. As such wrapper _`@context`_ needs to be referenced from a JSON-LD [Link]{.HTML-Code} 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 managed by their applications. 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 Loading Loading @@ -2311,8 +2313,8 @@ With a response as shown: <!-- 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 _`@context`_ in the JSON-LD [Link]{.HTML-Code} header of the HTTP Response or within the JSON-LD response payload body (when MIME type accepted is ["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 wrapper _`@context`_ hosted by itself, for instance, when there are inline Loading Loading @@ -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`_ which returns the following JSON-LD _`@context`_ referencing two files: Loading
md/clause-10.md +20 −15 Original line number Diff line number Diff line Loading @@ -1646,20 +1646,23 @@ Figure: Retrieve Entity use case ["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 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=<​version>"]{.HTML-Code} then the ContextBroker shall 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 Preference-Applied Header set to [Preference-Applied]{.HTML-Code} Header set to ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. - If the Accept Header is set to ["application/geo+json"]{.HTML-Code}, a GeoJSON _Feature_ object representing the entity as mandated by clause 5.2.6.11.1 and containing only the Attributes requested (if present): - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _Feature_ object will also contain an _`@context`_ field. - If the Prefer Header is set to ["body=json"]{.HTML-Code} the _`@context`_ is set as a Link Header and removed from the Feature object. - If the [Accept]{.HTML-Code} Header is set to ["application/geo+json"]{.HTML-Code}, a GeoJSON _Feature_ object representing the entity as mandated by clause 5.2.6.11.1 and containing only the Attributes requested (if present): - If the [Prefer]{.HTML-Code} Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _Feature_ object will also contain an _`@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 Loading Loading @@ -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 the Entities as mandated by clause 5.2.6.4.1 and containing only the 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=<​version>"]{.HTML-Code} then the ContextBroker shall 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, and return a Preference-Applied Header set to and return a [Preference-Applied]{.HTML-Code} Header set to ["ngsi-ld=<​conformant-version>"]{.HTML-Code} in the response. - If the Accept Header is set to ["application/geo+json",]{.HTML-Code} the response shall be a GeoJSON _FeatureCollection_ as mandated by clause 5.2.6.11.2, with each _Feature_ within the _FeatureCollection_ containing only the Attributes requested (if present): - If the Prefer Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _FeatureCollection_ will also contain an _`@context`_ field. - If the Prefer Header is set to ["body=json]{.HTML-Code}" the _`@context`_ is sent as a Link Header and removed from the _FeatureCollection_ object. - If the [Prefer]{.HTML-Code} Header is omitted or set to ["body=ld+json"]{.HTML-Code} then the _FeatureCollection_ will also contain an _`@context`_ field. - 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 Loading
md/clause-13.md +5 −5 Original line number Diff line number Diff line Loading @@ -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 (and implicitly) identified by any URL; [Context Brokers]{.HTML-Keyboard} only 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 best-practice, in order to exploit caching, is that clients do not embed their user** _`@contexts`_ **into their NGSI-LD documents**; instead clients should explicitly host their user _`@contexts`_ at their premises, or use the broker's capability to host user _`@contexts`_ on their behalf. the HTTP [Link]{.HTML-Code} header or as URLs in the payload body). Thus, the **recommended best-practice, in order to exploit caching, is that clients do not embed their user** _`@contexts`_ **into their NGSI-LD documents**; instead clients should explicitly host their user _`@contexts`_ at their premises, or use the broker's capability to host user _`@contexts`_ on their behalf. When an external _`@context`_ is stored, either explicitly upon a client's request or implicitly downloaded for caching purposes, the Context Broker Loading
md/clause-5.md +4 −4 Original line number Diff line number Diff line Loading @@ -3811,14 +3811,14 @@ following terms: mapping the Property name with its Property Identifier (URI). Whereas the Core NGSI-LD _`@context`_ contains JSON-LD Scoped Contexts, the user _`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8], Clause+++root.3.2.1), as described in Clause+++clause-8+++8.2.4, because this would enable overwriting terms defined in the Core NGSI-LD _`@context`_. _`@context`_ shall not contain JSON-LD Scoped Contexts (see [n.8], Section 4.1.8), as described in Clause+++clause-8+++8.2.4, because this would enable overwriting terms defined in the Core NGSI-LD _`@context`_. 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 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
md/clause-8.md +7 −6 Original line number Diff line number Diff line Loading @@ -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. 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 the JSON-LD specification [n.8], section 6.2. In case of HTTP binding via POST (see [i.16] ~clause 7.12.3.1), of the "Query Entities" operation, this means giving the _`@context`_ either via Link Header or within the payload body, depending on the Content-Type Header being ["application/json"]{.HTML-Code} or ["application/ld+json"]{.HTML-Code}, respectively. Entities" operation, this means using the JSON-LD [Link]{.HTML-Code} Header as described by the JSON-LD specification [n.8], section 6.2. In case of HTTP binding via POST (see [i.16] ~clause 7.12.3.1), of the "Query Entities" operation, this means giving the _`@context`_ either via [Link]{.HTML-Code} Header or within the payload body, depending on the Content-Type Header being ["application/json"]{.HTML-Code} or ["application/ld+json"]{.HTML-Code}, respectively. 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 Loading
