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

Merge branch 'master' into feature/value

parents 95fc25d2 09a0df74
Loading
Loading
Loading
Loading
Loading
+97 −35
Original line number Original line Diff line number Diff line
@@ -76,10 +76,6 @@ Such definition has been tested using [i.19].
      "@type": "@vocab"
      "@type": "@vocab"
    },
    },
    "attrs": "ngsi-ld:attrs",
    "attrs": "ngsi-ld:attrs",
    "avg": {
      "@id": "ngsi-ld:avg",
      "@container": "@list"
    },
    "bbox": {
    "bbox": {
      "@container": "@list",
      "@container": "@list",
      "@id": "geojson:bbox"
      "@id": "geojson:bbox"
@@ -123,10 +119,6 @@ Such definition has been tested using [i.19].
    },
    },
    "description": "http://purl.org/dc/terms/description",
    "description": "http://purl.org/dc/terms/description",
    "detail": "ngsi-ld:detail",
    "detail": "ngsi-ld:detail",
    "distinctCount": {
      "@id": "ngsi-ld:distinctCount",
      "@container": "@list"
    },
    "endAt": {
    "endAt": {
      "@id": "ngsi-ld:endAt",
      "@id": "ngsi-ld:endAt",
      "@type": "DateTime"
      "@type": "DateTime"
@@ -185,7 +177,17 @@ Such definition has been tested using [i.19].
    "jsonldContext": "ngsi-ld:jsonldContext",
    "jsonldContext": "ngsi-ld:jsonldContext",
    "jsons": {
    "jsons": {
      "@id": "ngsi-ld:jsons",
      "@id": "ngsi-ld:jsons",
      "@container": "@list",
      "@context": {
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
          "@container": "@list"
        }
      }
    },
    },
    "key": "ngsi-ld:hasKey",
    "key": "ngsi-ld:hasKey",
    "lang": "ngsi-ld:lang",
    "lang": "ngsi-ld:lang",
@@ -195,8 +197,18 @@ Such definition has been tested using [i.19].
    },
    },
    "languageMaps": {
    "languageMaps": {
      "@id": "ngsi-ld:hasLanguageMaps",
      "@id": "ngsi-ld:hasLanguageMaps",
      "@container": "@list",
      "@context": {
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
          "@container": "@list"
        },
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
        }
      }
    },
    "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
    "langString": "http://www.w3.org/1999/02/22-rdf-syntax-ns#langString",
    "lastFailure": {
    "lastFailure": {
      "@id": "ngsi-ld:lastFailure",
      "@id": "ngsi-ld:lastFailure",
@@ -220,14 +232,6 @@ Such definition has been tested using [i.19].
    "location": "ngsi-ld:location",
    "location": "ngsi-ld:location",
    "management": "ngsi-ld:management",
    "management": "ngsi-ld:management",
    "managementInterval": "ngsi-ld:managementInterval",
    "managementInterval": "ngsi-ld:managementInterval",
    "max": {
      "@id": "ngsi-ld:max",
      "@container": "@list"
    },
    "min": {
      "@id": "ngsi-ld:min",
      "@container": "@list"
    },
    "mode": "ngsi-ld:mode",
    "mode": "ngsi-ld:mode",
    "modifiedAt": {
    "modifiedAt": {
      "@id": "ngsi-ld:modifiedAt",
      "@id": "ngsi-ld:modifiedAt",
@@ -265,11 +269,31 @@ Such definition has been tested using [i.19].
    },
    },
    "objectLists": {
    "objectLists": {
      "@id": "ngsi-ld:hasObjectLists",
      "@id": "ngsi-ld:hasObjectLists",
      "@container": "@list",
      "@context": {
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
          "@container": "@list"
        },
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
        }
      }
    },
    "objects": {
    "objects": {
      "@id": "ngsi-ld:hasObjects",
      "@id": "ngsi-ld:hasObjects",
      "@container": "@list",
      "@context": {
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
          "@container": "@list"
        }
      }
    },
    },
    "objectType": {
    "objectType": {
      "@id": "ngsi-ld:hasObjectType",
      "@id": "ngsi-ld:hasObjectType",
@@ -377,14 +401,6 @@ Such definition has been tested using [i.19].
      "@id": "ngsi-ld:success",
      "@id": "ngsi-ld:success",
      "@type": "@id"
      "@type": "@id"
    },
    },
    "sum": {
      "@id": "ngsi-ld:sum",
      "@container": "@list"
    },
    "sumsq": {
      "@id": "ngsi-ld:sumsq",
      "@container": "@list"
    },
    "sysAttrs": "ngsi-ld:sysAttrs",
    "sysAttrs": "ngsi-ld:sysAttrs",
    "temporalQ": "ngsi-ld:temporalQ",
    "temporalQ": "ngsi-ld:temporalQ",
    "tenant": {
    "tenant": {
@@ -403,10 +419,6 @@ Such definition has been tested using [i.19].
    "timesFailed": "ngsi-ld:timesFailed",
    "timesFailed": "ngsi-ld:timesFailed",
    "timesSent": "ngsi-ld:timesSent",
    "timesSent": "ngsi-ld:timesSent",
    "title": "http://purl.org/dc/terms/title",
    "title": "http://purl.org/dc/terms/title",
    "totalCount": {
      "@id": "ngsi-ld:totalCount",
      "@container": "@list"
    },
    "triggerReason": "ngsi-ld:triggerReason",
    "triggerReason": "ngsi-ld:triggerReason",
    "typeList": {
    "typeList": {
      "@id": "ngsi-ld:typeList",
      "@id": "ngsi-ld:typeList",
@@ -431,12 +443,52 @@ Such definition has been tested using [i.19].
    },
    },
    "valueLists": {
    "valueLists": {
      "@id": "ngsi-ld:hasValueLists",
      "@id": "ngsi-ld:hasValueLists",
      "@container": "@list",
      "@context": {
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
          "@container": "@list"
        }
      }
    },
    },
    "values": {
    "values": {
      "@id": "ngsi-ld:hasValues",
      "@id": "ngsi-ld:hasValues",
      "@container": "@list",
      "@context": {
        "avg": {
          "@id": "ngsi-ld:avg",
          "@container": "@list"
          "@container": "@list"
        },
        },
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
        },
        "max": {
          "@id": "ngsi-ld:max",
          "@container": "@list"
        },
        "min": {
          "@id": "ngsi-ld:min",
          "@container": "@list"
        },
        "sum": {
          "@id": "ngsi-ld:sum",
          "@container": "@list"
        },
        "sumsq": {
          "@id": "ngsi-ld:sumsq",
          "@container": "@list"
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
        }
      }
    },
    "valueType": {
    "valueType": {
      "@id": "ngsi-ld:hasValueType",
      "@id": "ngsi-ld:hasValueType",
      "@type": "@vocab"
      "@type": "@vocab"
@@ -447,8 +499,18 @@ Such definition has been tested using [i.19].
    },
    },
    "vocabs": {
    "vocabs": {
      "@id": "ngsi-ld:hasVocabs",
      "@id": "ngsi-ld:hasVocabs",
      "@container": "@list",
      "@context": {
        "distinctCount": {
          "@id": "ngsi-ld:distinctCount",
          "@container": "@list"
          "@container": "@list"
        },
        },
        "totalCount": {
          "@id": "ngsi-ld:totalCount",
          "@container": "@list"
        }
      }
    },
    "watchedAttributes": {
    "watchedAttributes": {
      "@id": "ngsi-ld:watchedAttributes",
      "@id": "ngsi-ld:watchedAttributes",
      "@type": "@vocab"
      "@type": "@vocab"
+465 −45
Original line number Original line Diff line number Diff line
@@ -1036,7 +1036,7 @@ 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
attribute instances for speed; each is identified by a _`datasetId`_ and both
instances are represented in an array. The _`datasetId`_ enables individually
instances are represented in an array. The _`datasetId`_ enables individually
creating, updating and deleting a particular instance without affecting the
creating, updating and deleting a particular instance without affecting the
instance from another source
instance from another source.


```json
```json
{
{
@@ -1050,6 +1050,7 @@ instance from another source
        "type": "Property",
        "type": "Property",
        "value": "Speedometer"
        "value": "Speedometer"
      },
      },
      "observedAt": "2022-08-09T18:25:02Z",
      "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
      "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
    },
    },
    {
    {
@@ -1059,6 +1060,7 @@ instance from another source
        "type": "Property",
        "type": "Property",
        "value": "GPS"
        "value": "GPS"
      },
      },
      "observedAt": "2022-08-09T18:30:02Z",
      "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
      "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
    }
    }
  ],
  ],
@@ -1099,6 +1101,180 @@ level of the graph only.
}
}
```
```


##### C.2.2.4.3 Normalized Temporal multi-Attribute example

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.

```json
{
  "id": "urn:ngsi-ld:Vehicle:A4567",
  "type": "Vehicle",
  "speed": [
    {
      "type": "Property",
      "values": [
        {
          "value": 55,
          "source": {
            "type": "Property",
            "value": "Speedometer"
          },
          "instanceId": "urn:ngsi-ld:instance:31451425367",
          "observedAt": "2022-08-09T18:25:02Z"
        },
        {
          "value": 56,
          "source": {
            "type": "Property",
            "value": "Speedometer"
          },
          "instanceId": "urn:ngsi-ld:instance:23856477893",
          "observedAt": "2022-08-09T18:26:02Z"
        }
      ],
      "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
    },
    {
      "type": "Property",
      "values": [
        {
          "value": 54.5,
          "source": {
            "type": "Property",
            "value": "GPS"
          },
          "instanceId": "urn:ngsi-ld:instance:456234894533",
          "observedAt": "2022-08-09T18:30:02Z"
        },
        {
          "value": 54.5,
          "source": {
            "type": "Property",
            "value": "GPS"
          },
          "instanceId": "urn:ngsi-ld:instance:720930032567",
          "observedAt": "2022-08-09T18:33:02Z"
        }
      ],
      "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
    }
  ],
  "@context": [
    {
      "Vehicle": "http://example.org/Vehicle",
      "speed": "http://example.org/speed",
      "source": "http://example.org/hasSource"
    },
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
  ]
}
```

##### C.2.2.4.4 Simplified Temporal multi-Attribute example

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`_.

```json
{
  "id": "urn:ngsi-ld:Vehicle:A4567",
  "type": "Vehicle",
  "speed": [
    {
      "type": "Property",
      "values": [
        [55, "2022-08-09T18:25:02Z"],
        [56, "2022-08-09T18:26:02Z"]
      ],
      "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
    },
    {
      "type": "Property",
      "values": [
        [54.5, "2022-08-09T18:30:02Z"],
        [54.5, "2022-08-09T18:33:02Z"]
      ],
      "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
    }
  ],
  "@context": [
    {
      "Vehicle": "http://example.org/Vehicle",
      "speed": "http://example.org/speed"
    },
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
  ]
}
```

##### C.2.2.4.5 Aggregated Temporal multi-Attribute example

Below is an example, where aggregation 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`_.

```json
{
  "id": "urn:ngsi-ld:Vehicle:A4567",
  "type": "Vehicle",
  "speed": [
    {
      "type": "Property",
      "avg": [
        [55.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "max": [
        [56, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "min": [
        [55, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "distinctCount": [
        [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "totalCount": [
        [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "datasetId": "urn:ngsi-ld:Property:speedometerA4567-speed"
    },
    {
      "type": "Property",
      "avg": [
        [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "max": [
        [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "min": [
        [54.5, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "distinctCount": [
        [1, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "totalCount": [
        [2, "2022-08-09T18:25:00Z", "2022-08-09T18:30:00Z"]
      ],
      "datasetId": "urn:ngsi-ld:Property:gpsBxyz123-speed"
    }
  ],
  "@context": [
    {
      "Vehicle": "http://example.org/Vehicle",
      "speed": "http://example.org/speed"
    },
    "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
  ]
}
```

### C.2.3 Parking Entity
### C.2.3 Parking Entity


#### C.2.3.1 Normalized representation
#### C.2.3.1 Normalized representation
@@ -1841,9 +2017,14 @@ and implementers the following examples illustrate this concept.
The scenario starts with the creation of an Entity using a JSON-LD _`@context`_
The scenario starts with the creation of an Entity using a JSON-LD _`@context`_
as follows:
as follows:


- **POST**
**POST** [/ngsi-ld/v1/entities/]{.HTML-Variable}
- Content-Type: application/ld+json

- Content-Length: 200
**Request Headers**

- [Content-Type: application/ld+json]{.HTML-Code}
- [Content-Length: 200]{.HTML-Code}

**Request Body**


```json
```json
{
{
@@ -1910,11 +2091,18 @@ may be no longer known by the broker).
It is also interesting to note that the _`@context`_ array of the response
It is also interesting to note that the _`@context`_ array of the response
payload body contains, indeed, our header-supplied _`@context`_:
payload body contains, indeed, our header-supplied _`@context`_:


- **GET**
**GET**
- Accept: application/ld+json
[/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1]{.HTML-Variable}
- Link:

**Request Headers**

- [Accept: application/ld+json]{.HTML-Code}
- [Link:
  <​http://example.org/ngsi-ld/latest/parking-abbreviated.jsonld>;
  <​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
```json
{
{
@@ -1943,8 +2131,14 @@ payload body contains, indeed, our header-supplied _`@context`_:
Another interesting case to note is the one when an _`@context`_ with no
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:
matching terms or no _`@context`_ at all is supplied. See the following example:


- **GET**
**GET**
- Accept: application/ld+json
[/ngsi-ld/v1/entities/urn:ngsi-ld:OffStreetParking:Downtown1]{.HTML-Variable}

**Request Headers**

- [Accept: application/ld+json]{.HTML-Code}

**Response Body**


```json
```json
{
{
@@ -1974,27 +2168,28 @@ 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
<​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
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
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:


- 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
{
{
@@ -2006,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
As such wrapper _`@context`_ needs to be referenced from a JSON-LD
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
@@ -2019,15 +2215,25 @@ tools. However, it should be noted this is not necessary for NGSI-LD, as the
Core _`@context`_ is always implicitly included.
Core _`@context`_ is always implicitly included.


Then, using such wrapper _`@context`_, (in our example hosted at
Then, using such wrapper _`@context`_, (in our example hosted at
https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld), the developer
_`https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld`_), the
will be able to issue requests like:
developer will be able to issue requests like:


- **POST**
<!-- prettier-ignore-start -->
- Content-Type: application/json

- Content-Length: 200
>>> [!tip] EXAMPLE 1:
- Link:

**POST** [/ngsi-ld/v1/entities/]{.HTML-Variable}

**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;;
  &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
```json
{
{
@@ -2045,21 +2251,45 @@ will be able to issue requests like:
}
}
```
```


- 201 Created
With a response as shown:
- Location: /ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1

- Link:
**Status Code:** 201 Created
  &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"
**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&gt;;
  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** [/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:V1]{.HTML-Variable}


&#8203;
**Request Headers**


- **GET**
- Accept: [application/ld+json]{.HTML-Code}
- Accept: application/ld+json
- [Link:
- Link:
  &lt;&#8203;https://hosting.example.com/ngsi-ld/v1/wrapper-context.jsonld&gt;;
  &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";
- 200 OK
  type="application/ld+json"]{.HTML-Code}
- Content-Type: application/ld+json

With a response as shown:

**Status Code:** 200 OK

**Response Headers**

- [Content-Type: application/ld+json]{.HTML-Code}

**Response Body**


```json
```json
{
{
@@ -2078,9 +2308,13 @@ will be able to issue requests like:
}
}
```
```


>>>

<!-- 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
@@ -2088,6 +2322,72 @@ _`@context`_ terms or when the Core _`@context`_ has not been previously
included by the wrapper _`@context`_ (not recommended) provided within
included by the wrapper _`@context`_ (not recommended) provided within
developer's requests.
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 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:

```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
## C.8 \@context processing clarifications


JSON-LD Specification [n.8] says that "If a term is redefined within a context,
JSON-LD Specification [n.8] says that "If a term is redefined within a context,
@@ -2278,3 +2578,123 @@ Entity of type "Store" with two Properties. The "address" Property is digitally
>>>
>>>


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

## C.11 Scope Queries

As specified in Clause 7.2.5, the Scope Query language is intended to select
only those Entities that are within the specified Scope(s). Scopes are specified
as a disjunction of elements, where each element can either directly be a Scope
or a conjunction of multiple Scopes.

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

>>> [!tip] EXAMPLE:

Give back all the Entities of type ["OffStreetParking"]{.HTML-Code} that are
within the Scope [/Madrid/Centro]{.HTML-Code} or [/Madrid/Cortes]{.HTML-Code}.

**GET**
[/ngsi-ld/v1/entities/?type=OffStreetParking&scopeQ="/Madrid/Centro,/Madrid/Cortes"]{.HTML-Variable}

**Request Headers**

- [Accept: application/ld+json]{.HTML-Code}
- [Link:
  &lt;&#8203;http://example.org/ngsi-ld/latest/parking.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/ld+json]{.HTML-Code}
- [Content-Length: 1784]{.HTML-Code}

**Response Body**

```json
[
  {
    "id": "urn:ngsi-ld:OffStreetParking:Downtown1",
    "type": "OffStreetParking",
    "scope": "/Madrid/Centro",
    "name": {
      "type": "Property",
      "value": "Downtown One"
    },
    "availableSpotNumber": {
      "type": "Property",
      "value": 121,
      "observedAt": "2017-07-29T12:05:02Z",
      "reliability": {
        "type": "Property",
        "value": 0.7
      },
      "providedBy": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:Camera:C1"
      }
    },
    "totalSpotNumber": {
      "type": "Property",
      "value": 200
    },
    "location": {
      "type": "GeoProperty",
      "value": {
        "type": "Point",
        "coordinates": [-8.5, 41.2]
      }
    },
    "@context": [
      "http://example.org/ngsi-ld/latest/parking.jsonld",
      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
    ]
  },
  {
    "id": "urn:ngsi-ld:OffStreetParking:Corte4",
    "type": "OffStreetParking",
    "scope": ["/Madrid/Cortes", "/Company894/UnitC"],
    "name": {
      "type": "Property",
      "value": "Corte4"
    },
    "availableSpotNumber": {
      "type": "Property",
      "value": 121,
      "observedAt": "2017-07-29T12:05:02Z",
      "reliability": {
        "type": "Property",
        "value": 0.7
      },
      "providedBy": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:Camera:C1"
      }
    },
    "totalSpotNumber": {
      "type": "Property",
      "value": 100
    },
    "location": {
      "type": "GeoProperty",
      "value": {
        "type": "Point",
        "coordinates": [-8.6, 41.3]
      }
    },
    "@context": [
      "http://example.org/ngsi-ld/latest/parking.jsonld",
      "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld"
    ]
  }
]
```

>>>

<!-- prettier-ignore-end -->
+2 −161

File changed.

Preview size limit exceeded, changes collapsed.

+106 −2
Original line number Original line Diff line number Diff line
# Annex E [(informative)]{.inform}: RDF-compatible specification of NGSI-LD meta-model
# Annex E [(informative)]{.inform}: Conventions and syntax guidelines


The content of this annex is now in ETSI TS 104 178 [i.6].
When new terms are defined, they are marked in bold, and terms are capitalized
thereafter.

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

>>> [!tip] EXAMPLE 1:

**NGSI-LD Linked Entity**, [Linked Entity]{.HTML-Keyboard}.

>>>

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

API Parameter names are always in lowercase.

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

>>> [!tip] EXAMPLE 2:

_`options`_.

>>>

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

Entity Types are defined using lowercase but with a starting capital letter.

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

>>> [!tip] EXAMPLE 3:

Vehicle, Building, ParkingSpace.

>>>

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

JSON-LD nodes and terms are always defined using camel case notation starting
with lower case.

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

>>> [!tip] EXAMPLE 4:

_`createdAt`_, _`value`_, _`unitCode`_.

>>>

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

When referring to special terms, data types or words defined previously in the
present document or by other referenced specifications, italics format is used.

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

>>> [!tip] EXAMPLE 5:

_ListRelationship_, _GeoProperty_, _Geometry_, _Second_, _Number_.

>>>

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

When referring to literal strings double quotes are used.

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

>>> [!tip] EXAMPLE 6:

["application/json"]{.HTML-Code}, ["Subscription"]{.HTML-Code}.

>>>

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

When referring to the JSON-LD Context the mnemonic text string _`@context`_ is
used as a placeholder.

All the dates and times are given in UTC format.

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

>>> [!tip] EXAMPLE 7:

[2018-02-09T11:00:00Z]{.HTML-Code}.

>>>

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

The measurement units used in the API are those defined by the International
System of Units.

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

>>> [!tip] EXAMPLE 8:

The distance in geo-queries is provided in meters.

>>>

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

When defining application-specific elements or API extensions the same
conventions and syntax guidelines should be followed.
+225 −100

File changed.

Preview size limit exceeded, changes collapsed.

Loading