Commit d8d4bf5a authored by Jason Fox's avatar Jason Fox
Browse files

Extend examples.

parent bc60c39e
Loading
Loading
Loading
Loading
+154 −32
Original line number Diff line number Diff line
@@ -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:

<!-- 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:
  &lt;&#8203;https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld&gt;;
  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:
  &lt;&#8203;https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld&lt;;
  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}

>>>

&#8203;
<!-- prettier-ignore-end -->

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

>>> [!tip] EXAMPLE 2:

**GET** [/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1]{.HTML-Variable}

- **GET**
- Accept: application/ld+json
- Link:
**Request Headers**

- Accept: [application/ld+json]{.HTML-Code}
- [Link:
  &lt;&#8203;https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld&gt;;
  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:
}
```

>>>

<!-- 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
@@ -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.

<!-- 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:
  &lt;&#8203;http://example.org/vehicle/v1/vehicle-context.jsonld&gt;;
  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:
  &lt;&#8203;http://**&lt;&#8203;context-broker&gt;**/ngsi-ld/v1/jsonldContexts/http%3A%2F%2Fexample.org%2Fngsi-ld%2Flatest%2Fvehicle.jsonld?core=1.9&gt;
  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,