diff --git a/.env b/.env index a35fab9..9cc389f 100644 --- a/.env +++ b/.env @@ -4,7 +4,7 @@ EXPOSED_PORT=1026 # Orion LD variables ORION_LD_PORT=1026 -ORION_LD_VERSION=1.5.1 +ORION_LD_VERSION=1.6.0-pre-1572 # Scorpio variables SCORPIO_PORT=9090 diff --git a/FIWARE Linked Data.postman_collection.json b/FIWARE Linked Data.postman_collection.json index 29b6627..636a46a 100644 --- a/FIWARE Linked Data.postman_collection.json +++ b/FIWARE Linked Data.postman_collection.json @@ -30,961 +30,9 @@ "description": "This tutorial recreates the same data entities as the intial _\"Powered by FIWARE\"_ supermarket finder app, but using\nNGSI-LD linked data entities rather than NGSI v2.\n\n## Checking the service health\n\nAs usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.\n\nThe format of the response has not changed. The `release_date` must be 16th July 2019 or later to be able to\nwork with the requests defined below." }, "response": [] - }, - { - "name": "Obtain full Linked Data model context", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{datamodels-context.jsonld}}", - "host": [ - "{{datamodels-context.jsonld}}" - ] - }, - "description": "Information about the data models and relationships used within this tutorial\ncan be obtained by requesting the full `@context` and `@graph`." - }, - "response": [] - }, - { - "name": "Creating your first Data Entity", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Type", - "value": "application/ld+json" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"Property\",\n \"value\": [\"commercial\"]\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Bornholmer Straße 65\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Prenzlauer Berg\",\n \"postalCode\": \"10439\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3986, 52.5547]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Bösebrücke Einkauf\"\n },\n \"@context\": [\n \"https://smartdatamodels.org/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\"\n ]\n}" - }, - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ] - }, - "description": "## Creating Context Data\n\nWhen creating linked data entities, it is important to use common data models. This will allow us to easily combine data\nfrom multiple sources and remove ambiguity when comparing data coming from different sources.\n\nCreating linked data using full qualified names throughout would be painful, as each attribute would need to be a URN,\nso JSON-LD introduces the idea of an `@context` attribute which can hold pointers to context definitions. To add a\nFIWARE [Building](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html) data entity,\nthe following `@context` would be required\n\n```json\n{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n ... other data attributes\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\n### Core Context\n\n[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld)\nrefers to the Core `@context` of NSGI-LD, this defines element such as `id` and `type` which are common to all NGSI\nentities, as well as defining terms such as `Property` and `Relationship`. The core context is so fundamental to\nNGSI-LD, that it is added by default to any `@context` sent to a request.\n\n### FIWARE Data Models\n\n[https://smartdatamodels.org/context.jsonld](https://smartdatamodels.org/context.jsonld)\nrefers to the definition of standard data models supplied by FIWARE. Adding this to the `@context` will load the\ndefinitions of all the [data models](https://fiware-datamodels.readthedocs.io) defined by the FIWARE Foundation, a\nsummary of the FQNs related to **Building** can be seen below:\n\n```json\n{\n \"@context\": {\n \"Building\": \"https://uri.fiware.org/ns/datamodels/Building\",\n ... etc\n \"address\": \"http://schema.org/address\",\n \"category\": \"https://uri.fiware.org/ns/datamodels/category\",\n \"location\": \"http://uri.etsi.org/ngsi-ld/location\",\n \"name\": \"http://schema.org/name\",\n ...etc\n }\n}\n```\n\nIf we include this context definition, it means that we will be able to use short names for `Building`, `address`,\n`location` for our entities, but computers will also be able to read the FNQs when comparing with other sources.\n\nTo create a valid **Building** data entity in the context broker, make a POST request to the\n`http://localhost:1026/ngsi-ld/v1/entities` endpoint as shown below. It is essential that the appropriate\n`Content-Type: application/ld+json` is also used, so that the data entity is recognized as Linked data.\n\nThe first request will take some time, as the context broker must navigate and load all of the files mentioned in the\n`@context`.\n\n\n> **Note**: if `https://smartdatamodels.org/context.jsonld` is unavailable for some reason the request will fail\n>\n> For a working production system it is essential that the `@context` files are always available to ensure third parties can\n> read the context. High availability infrastructure has not been considered for this tutorial to keep the architecture simple." - }, - "response": [] - }, - { - "name": "Creating your Second Data Entity", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Type", - "value": "application/ld+json" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store002\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"Property\",\n \"value\": [\"commercial\"]\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Friedrichstraße 44\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Kreuzberg\",\n \"postalCode\": \"10969\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3903, 52.5075]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Checkpoint Markt\"\n },\n \"@context\": [\n \"https://smartdatamodels.org/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\"\n ]\n}" - }, - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ] - }, - "description": "Each subsequent entity must have a unique `id` for the given `type`.\n\n### Defining Properties within the NGSI-LD entity definition\n\nThe attributes `id` and `type` should be familiar to anyone who has used NSGI v2, and these have not changed. As\nmentioned above, the type should refer to an included data model, in this case `Building` is being used as a short name\nfor the inclued URN `https://uri.fiware.org/ns/datamodels/Building`. Thereafter each _property_ is defined as a JSON\nelement containing two attributes, a `type` and a `value`.\n\nThe `type` of a _property_ attribute must be one of the following:\n\n- `\"GeoProperty\"`: `\"http://uri.etsi.org/ngsi-ld/GeoProperty\"` for locations. Locations should be specified as\n Longitude-Latitude pairs in [GeoJSON format](https://tools.ietf.org/html/rfc7946). The preferred name for the\n primary location attribute is `location`\n- `\"TemporalProperty\"`: `\"http://uri.etsi.org/ngsi-ld/TemporalProperty\"` for time-based values. Temporal properties\n should be Date, Time or DateTime strings encoded be [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - e.g.\n `YYYY-MM-DDThh:mm:ssZ`\n- `\"Property\"`: `\"http://uri.etsi.org/ngsi-ld/Property\"` - for everything else\n\n> **Note:** that for simplicity, this data entity has no relationships defined. Relationships must be given the\n> `type=\"Relationship`. Relationships will be discusssed in a subsequent tutorial.\n\n### Defining Properties-of-Properties within the NGSI-LD entity definition\n\n_Properties-of-Properties_ is the NGSI-LD equivalent of metadata (i.e. _\"data about data\"_), it is use to describe\nproperties of the attribute value itself like accuracy, provider, or the units to be used. Some built-in metadata\nattributes already exist and these names are reserved:\n\n- `createdAt` (type: DateTime): attribute creation date as an ISO 8601 string.\n- `modifiedAt` (type: DateTime): attribute modification date as an ISO 8601 string.\n\nAdditionally `observedAt`, `datasetId` and `instanceId` may optionally be added in some cases, and `location`,\n`observationSpace` and `operationSpace` have special meaning for Geoproperties.\n\nIn the examples given above, one element of metadata (i.e. a _property-of-a-property_) can be found within the `address`\nattribute. a `verified` flag indicates whether the address has been confirmed. The commonest _property-of-a-property_ is\n`unitCode` which should be used to hold the UN/CEFACT\n[Common Codes](http://wiki.goodrelations-vocabulary.org/Documentation/UN/CEFACT_Common_Codes) for Units of Measurement." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by FNQ type", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", - "disabled": true - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities?type=https://uri.fiware.org/ns/data-models%23Building", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities" - ], - "query": [ - { - "key": "type", - "value": "https://uri.fiware.org/ns/data-models%23Building" - } - ] - }, - "description": "This example returns the data of all `Building` entities within the context data The `type` parameter is mandatory for\nNGSI-LD and is used to filter the response.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible.\n\n- `id`, `type` and `location` are defined in the core context and are not expanded.\n- `address` has been mapped to `http://schema.org/address`\n- `name` has been mapped to `http://schema.org/name`\n- `category` has been mapped to `https://uri.fiware.org/ns/datamodels#category`\n\nNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\n**always** be displayed." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by id", - "request": { - "method": "GET", - "header": [ - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "urn:ngsi-ld:Building:store001" - ], - "query": [ - { - "key": "type", - "value": "Store", - "description": "Entity type, to avoid ambiguity in case there are several entities with the same entity id", - "disabled": true - }, - { - "key": "attrs", - "value": "name", - "description": "Ordered list of attribute names to display", - "disabled": true - } - ] - }, - "description": "This example returns the data of `urn:ngsi-ld:Building:store001`.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by type and linked context", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities?type=Building&options=keyValues", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "If a reference to the supplied data is supplied, it is possible to return short name data and limit responses to a\nspecific `type` of data. For example, the request below returns the data of all `Building` entities within the context\ndata. Use of the `type` parameter limits the response to `Building` entities only, use of the `options=keyValues` query\nparameter reduces the response down to standard JSON-LD.\n\nA [`Link` header](https://www.w3.org/wiki/LinkHeader) must be supplied to associate the short form `type=\"Building\"`\nwith the FNQ `https://uri.fiware.org/ns/datamodels/Building`. The full link header syntax can be seen below:\n\n```text\nLink: ; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\n```\n\nThe standard HTTP `Link` header allows metadata (in this case the `@context`) to be passed in without actually touching\nthe resource in question. In the case of NGSI-LD, the metadata is a file of in `application/ld+json` format.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute defintions\n`type=\"Property\"` or any _properties-of-properties_ elements. You can see that `Link` header from the request has been\nused as the `@context` returned in the response." - }, - "response": [] - }, - { - "name": "Filter context data by attribute value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Building&q=name==\"Checkpoint Markt\"&options=keyValues", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "name==\"Checkpoint Markt\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns all `Building` entiies with the `name` attribute _Checkpoint Markt_. Filtering can be done using\nthe `q` parameter - if a string has spaces in it, it can be URL encoded and held within single quote characters `'` =\n`%27`.\n\nThe `Link` header `https://smartdatamodels.org/context.jsonld` holds an array of `@context` as shown:\n\n```json\n{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\nand therefore includes the FIWARE Building model.\n\nThis means that use of the `Link` header and the `options=keyValues` parameter reduces the response to short form\nJSON-LD as shown:" - }, - "response": [] - }, - { - "name": "Filter context data by attribute in an Array", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Building&q=category==\"commercial\",\"office\"&options=keyValues", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "category==\"commercial\",\"office\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "Within the standard `Building` model, the `category` attribute refers to an array of strings. This example returns all\n`Building` entities with a `category` attribute which contains either `commercial` or `office` strings. Filtering can be\ndone using the `q` parameter, comma separating the acceptable values.\n\nThe response is returned in JSON-LD format with short form attribute names" - }, - "response": [] - }, - { - "name": "Filter context data by sub-attribute value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Building&q=address%5BaddressLocality%5D==\"Kreuzberg\"&options=keyValues", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "address%5BaddressLocality%5D==\"Kreuzberg\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns all stores found in the Kreuzberg District.\n\nFiltering can be done using the `q` parameter - sub-attributes are annotated using the bracket syntax e.g.\n`q=address[addressLocality]==Kreuzberg`. This differs from NGSI v2 where dot syntax was used.\n\nUse of the `Link` header and the `options=keyValues` parameter reduces the response to JSON-LD." - }, - "response": [] - }, - { - "name": "Filter context data by metadata value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Building&q=address.verified==true&options=keyValues", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "address.verified==true" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns the data of all `Building` entities with a verified address. The `verified` attribute is an example\nof a _Property-of-a-Property_\n\nMetadata queries (i.e. Properties of Properties) are annotated using the dot syntax e.g. `q=address.verified==true`.\nThis supercedes the `mq` parameter from NGSI v2.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." - }, - "response": [] - }, - { - "name": "Filter context data by distance", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{orion}}/ngsi-ld/v1/entities/?type=Building&geometry=Point&coordinates=%5B13.3777,52.5162%5D&georel=near;maxDistance==2000&options=keyValues", - "protocol": "http", - "host": [ - "{{orion}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "geometry", - "value": "Point" - }, - { - "key": "coordinates", - "value": "%5B13.3777,52.5162%5D" - }, - { - "key": "georel", - "value": "near;maxDistance==2000", - "description": "Ordered list of attribute names to display" - }, - { - "key": "options", - "value": "keyValues" - } - ] - }, - "description": "This example return all Stores within 2km the **Brandenburg Gate** in **Berlin** (_52.5162N 13.3777W_). To make a\ngeo-query request, three parameters must be specified, `geometry`, `coordinates` and `georel`.\n\nThe syntax for NGSI-LD has been updated, the `coordinates` parameter is now represented in\n[geoJSON](https://tools.ietf.org/html/rfc7946) including the square brackets rather than the simple lat-long pairs\nrequired in NGSI v2.\n\nNote that by default the geo-query will be applied to the `location` attribute, as this is default specified in NGSI-LD.\nIf another attribute is is to be used, an additional `geoproperty` parameter is required.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." - }, - "response": [] - } - ], - "description": "# Architecture\n\nThe demo application will send and receive NGSI-LD calls to a compliant context broker. Since both NSGI v2 and NSGI-LD\ninterfaces are available to an experimental version fo the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/), our demo application will only make use of one\nFIWARE component.\n\nCurrently, the Orion Context Broker relies on open source [MongoDB](https://www.mongodb.com/) technology to keep\npersistence of the context data it holds. Therefore, the architecture will consist of two elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using\n [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the Orion Context Broker to hold context data information such as data entities, subscriptions and\n registrations\n\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.\n\n![](https://fiware.github.io/tutorials.Linked-Data/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of the associated `docker-compose.yml` file:\n\n```yaml\norion:\n image: fiware/orion-ld\n hostname: orion\n container_name: fiware-orion\n depends_on:\n - mongo-db\n networks:\n - default\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n healthcheck:\n test: curl --fail -s http://orion:1026/version || exit 1\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --nojournal\n```\n\nBoth containers are residing on the same network - the Orion Context Broker is listening on Port `1026` and MongoDB is\nlistening on the default port `27071`. Both containers are also exposing the same ports externally - this is purely for\nthe tutorial access - so that cUrl or Postman can access them without being part of the same network. The command-line\ninitialization should be self explanatory.\n\nThe only notable difference to the introductory tutorials is that the required image name is currently\n`fiware/orion-ld`.\n\n# Start Up\n\nAll services can be initialised from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.Linked-Data/blob/master/services) Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:\n\n```bash\ngit clone git@github.com:FIWARE/tutorials.Linked-Data.git\ncd tutorials.Linked-Data\n\n./services orion\n```\n\n\n> **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n> ```\n> ./services stop\n> ```\n", - "event": [ - { - "listen": "prerequest", - "script": { - "type": "text/javascript", - "exec": [ - "" - ] - } - }, - { - "listen": "test", - "script": { - "type": "text/javascript", - "exec": [ - "" - ] - } - } - ] - }, - { - "name": "Linked Data using Scorpio", - "item": [ - { - "name": "Obtaining Version Information", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "http://{{scorpio}}/scorpio/v1/info/", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "scorpio", - "v1", - "info", - "" - ] - }, - "description": "This tutorial recreates the same data entities as the intial _\"Powered by FIWARE\"_ supermarket finder app, but using\nNGSI-LD linked data entities rather than NGSI v2.\n\n## Checking the service health\n\nAs usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.\n\nThe format of the response has not changed. The `release_date` must be 16th July 2019 or later to be able to\nwork with the requests defined below." - }, - "response": [] - }, - { - "name": "Obtain full Linked Data model context", - "request": { - "method": "GET", - "header": [], - "url": { - "raw": "{{datamodels-context.jsonld}}", - "host": [ - "{{datamodels-context.jsonld}}" - ] - }, - "description": "Information about the data models and relationships used within this tutorial\ncan be obtained by requesting the full `@context` and `@graph`." - }, - "response": [] - }, - { - "name": "Creating your first Data Entity", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Type", - "value": "application/ld+json" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"Property\",\n \"value\": [\"commercial\"]\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Bornholmer Straße 65\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Prenzlauer Berg\",\n \"postalCode\": \"10439\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3986, 52.5547]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Bösebrücke Einkauf\"\n },\n \"@context\": [\n \"https://smartdatamodels.org/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\"\n ]\n}" - }, - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ] - }, - "description": "## Creating Context Data\n\nWhen creating linked data entities, it is important to use common data models. This will allow us to easily combine data\nfrom multiple sources and remove ambiguity when comparing data coming from different sources.\n\nCreating linked data using full qualified names throughout would be painful, as each attribute would need to be a URN,\nso JSON-LD introduces the idea of an `@context` attribute which can hold pointers to context definitions. To add a\nFIWARE [Building](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html) data entity,\nthe following `@context` would be required\n\n```json\n{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n ... other data attributes\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\n### Core Context\n\n[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld)\nrefers to the Core `@context` of NSGI-LD, this defines element such as `id` and `type` which are common to all NGSI\nentities, as well as defining terms such as `Property` and `Relationship`. The core context is so fundamental to\nNGSI-LD, that it is added by default to any `@context` sent to a request.\n\n### FIWARE Data Models\n\n[https://smartdatamodels.org/context.jsonld](https://smartdatamodels.org/context.jsonld)\nrefers to the definition of standard data models supplied by FIWARE. Adding this to the `@context` will load the\ndefinitions of all the [data models](https://fiware-datamodels.readthedocs.io) defined by the FIWARE Foundation, a\nsummary of the FQNs related to **Building** can be seen below:\n\n```json\n{\n \"@context\": {\n \"Building\": \"https://uri.fiware.org/ns/datamodels/Building\",\n ... etc\n \"address\": \"http://schema.org/address\",\n \"category\": \"https://uri.fiware.org/ns/datamodels/category\",\n \"location\": \"http://uri.etsi.org/ngsi-ld/location\",\n \"name\": \"http://schema.org/name\",\n ...etc\n }\n}\n```\n\nIf we include this context definition, it means that we will be able to use short names for `Building`, `address`,\n`location` for our entities, but computers will also be able to read the FNQs when comparing with other sources.\n\nTo create a valid **Building** data entity in the context broker, make a POST request to the\n`http://localhost:1026/ngsi-ld/v1/entities` endpoint as shown below. It is essential that the appropriate\n`Content-Type: application/ld+json` is also used, so that the data entity is recognized as Linked data.\n\nThe first request will take some time, as the context broker must navigate and load all of the files mentioned in the\n`@context`.\n\n\n> **Note**: if `https://smartdatamodels.org/context.jsonld` is unavailable for some reason the request will fail\n>\n> For a working production system it is essential that the `@context` files are always available to ensure third parties can\n> read the context. High availability infrastructure has not been considered for this tutorial to keep the architecture simple." - }, - "response": [] - }, - { - "name": "Creating your Second Data Entity", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Type", - "value": "application/ld+json" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store002\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"Property\",\n \"value\": [\"commercial\"]\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Friedrichstraße 44\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Kreuzberg\",\n \"postalCode\": \"10969\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3903, 52.5075]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Checkpoint Markt\"\n },\n \"@context\": [\n \"https://smartdatamodels.org/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\"\n ]\n}" - }, - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ] - }, - "description": "Each subsequent entity must have a unique `id` for the given `type`.\n\n### Defining Properties within the NGSI-LD entity definition\n\nThe attributes `id` and `type` should be familiar to anyone who has used NSGI v2, and these have not changed. As\nmentioned above, the type should refer to an included data model, in this case `Building` is being used as a short name\nfor the inclued URN `https://uri.fiware.org/ns/datamodels/Building`. Thereafter each _property_ is defined as a JSON\nelement containing two attributes, a `type` and a `value`.\n\nThe `type` of a _property_ attribute must be one of the following:\n\n- `\"GeoProperty\"`: `\"http://uri.etsi.org/ngsi-ld/GeoProperty\"` for locations. Locations should be specified as\n Longitude-Latitude pairs in [GeoJSON format](https://tools.ietf.org/html/rfc7946). The preferred name for the\n primary location attribute is `location`\n- `\"TemporalProperty\"`: `\"http://uri.etsi.org/ngsi-ld/TemporalProperty\"` for time-based values. Temporal properties\n should be Date, Time or DateTime strings encoded be [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - e.g.\n `YYYY-MM-DDThh:mm:ssZ`\n- `\"Property\"`: `\"http://uri.etsi.org/ngsi-ld/Property\"` - for everything else\n\n> **Note:** that for simplicity, this data entity has no relationships defined. Relationships must be given the\n> `type=\"Relationship`. Relationships will be discusssed in a subsequent tutorial.\n\n### Defining Properties-of-Properties within the NGSI-LD entity definition\n\n_Properties-of-Properties_ is the NGSI-LD equivalent of metadata (i.e. _\"data about data\"_), it is use to describe\nproperties of the attribute value itself like accuracy, provider, or the units to be used. Some built-in metadata\nattributes already exist and these names are reserved:\n\n- `createdAt` (type: DateTime): attribute creation date as an ISO 8601 string.\n- `modifiedAt` (type: DateTime): attribute modification date as an ISO 8601 string.\n\nAdditionally `observedAt`, `datasetId` and `instanceId` may optionally be added in some cases, and `location`,\n`observationSpace` and `operationSpace` have special meaning for Geoproperties.\n\nIn the examples given above, one element of metadata (i.e. a _property-of-a-property_) can be found within the `address`\nattribute. a `verified` flag indicates whether the address has been confirmed. The commonest _property-of-a-property_ is\n`unitCode` which should be used to hold the UN/CEFACT\n[Common Codes](http://wiki.goodrelations-vocabulary.org/Documentation/UN/CEFACT_Common_Codes) for Units of Measurement." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by FNQ type", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", - "disabled": true - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities?type=https://uri.fiware.org/ns/data-models%23Building", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities" - ], - "query": [ - { - "key": "type", - "value": "https://uri.fiware.org/ns/data-models%23Building" - } - ] - }, - "description": "This example returns the data of all `Building` entities within the context data The `type` parameter is mandatory for\nNGSI-LD and is used to filter the response.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible.\n\n- `id`, `type` and `location` are defined in the core context and are not expanded.\n- `address` has been mapped to `http://schema.org/address`\n- `name` has been mapped to `http://schema.org/name`\n- `category` has been mapped to `https://uri.fiware.org/ns/datamodels#category`\n\nNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\n**always** be displayed." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by id", - "request": { - "method": "GET", - "header": [ - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "urn:ngsi-ld:Building:store001" - ], - "query": [ - { - "key": "type", - "value": "Store", - "description": "Entity type, to avoid ambiguity in case there are several entities with the same entity id", - "disabled": true - }, - { - "key": "attrs", - "value": "name", - "description": "Ordered list of attribute names to display", - "disabled": true - } - ] - }, - "description": "This example returns the data of `urn:ngsi-ld:Building:store001`.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by type and linked context", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities?type=Building&options=keyValues", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "If a reference to the supplied data is supplied, it is possible to return short name data and limit responses to a\nspecific `type` of data. For example, the request below returns the data of all `Building` entities within the context\ndata. Use of the `type` parameter limits the response to `Building` entities only, use of the `options=keyValues` query\nparameter reduces the response down to standard JSON-LD.\n\nA [`Link` header](https://www.w3.org/wiki/LinkHeader) must be supplied to associate the short form `type=\"Building\"`\nwith the FNQ `https://uri.fiware.org/ns/datamodels/Building`. The full link header syntax can be seen below:\n\n```text\nLink: ; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\n```\n\nThe standard HTTP `Link` header allows metadata (in this case the `@context`) to be passed in without actually touching\nthe resource in question. In the case of NGSI-LD, the metadata is a file of in `application/ld+json` format.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute defintions\n`type=\"Property\"` or any _properties-of-properties_ elements. You can see that `Link` header from the request has been\nused as the `@context` returned in the response." - }, - "response": [] - }, - { - "name": "Filter context data by attribute value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/?type=Building&q=name==\"Checkpoint Markt\"&options=keyValues", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "name==\"Checkpoint Markt\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns all `Building` entiies with the `name` attribute _Checkpoint Markt_. Filtering can be done using\nthe `q` parameter - if a string has spaces in it, it can be URL encoded and held within single quote characters `'` =\n`%27`.\n\nThe `Link` header `https://smartdatamodels.org/context.jsonld` holds an array of `@context` as shown:\n\n```json\n{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\nand therefore includes the FIWARE Building model.\n\nThis means that use of the `Link` header and the `options=keyValues` parameter reduces the response to short form\nJSON-LD as shown:" - }, - "response": [] - }, - { - "name": "Filter context data by attribute in an Array", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/?type=Building&q=category==\"commercial\",\"office\"&options=keyValues", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "category==\"commercial\",\"office\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "Within the standard `Building` model, the `category` attribute refers to an array of strings. This example returns all\n`Building` entities with a `category` attribute which contains either `commercial` or `office` strings. Filtering can be\ndone using the `q` parameter, comma separating the acceptable values.\n\nThe response is returned in JSON-LD format with short form attribute names" - }, - "response": [] - }, - { - "name": "Filter context data by sub-attribute value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/?type=Building&q=address%5BaddressLocality%5D==\"Kreuzberg\"&options=keyValues", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "address%5BaddressLocality%5D==\"Kreuzberg\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns all stores found in the Kreuzberg District.\n\nFiltering can be done using the `q` parameter - sub-attributes are annotated using the bracket syntax e.g.\n`q=address[addressLocality]==Kreuzberg`. This differs from NGSI v2 where dot syntax was used.\n\nUse of the `Link` header and the `options=keyValues` parameter reduces the response to JSON-LD." - }, - "response": [] - }, - { - "name": "Filter context data by metadata value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/?type=Building&q=address.verified==true&options=keyValues", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "address.verified==true" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns the data of all `Building` entities with a verified address. The `verified` attribute is an example\nof a _Property-of-a-Property_\n\nMetadata queries (i.e. Properties of Properties) are annotated using the dot syntax e.g. `q=address.verified==true`.\nThis supercedes the `mq` parameter from NGSI v2.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." - }, - "response": [] - }, - { - "name": "Filter context data by distance", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{scorpio}}/ngsi-ld/v1/entities/?type=Building&geometry=Point&coordinates=%5B13.3777,52.5162%5D&georel=near;maxDistance==2000&options=keyValues", - "protocol": "http", - "host": [ - "{{scorpio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "geometry", - "value": "Point" - }, - { - "key": "coordinates", - "value": "%5B13.3777,52.5162%5D" - }, - { - "key": "georel", - "value": "near;maxDistance==2000", - "description": "Ordered list of attribute names to display" - }, - { - "key": "options", - "value": "keyValues" - } - ] - }, - "description": "This example return all Stores within 2km the **Brandenburg Gate** in **Berlin** (_52.5162N 13.3777W_). To make a\ngeo-query request, three parameters must be specified, `geometry`, `coordinates` and `georel`.\n\nThe syntax for NGSI-LD has been updated, the `coordinates` parameter is now represented in\n[geoJSON](https://tools.ietf.org/html/rfc7946) including the square brackets rather than the simple lat-long pairs\nrequired in NGSI v2.\n\nNote that by default the geo-query will be applied to the `location` attribute, as this is default specified in NGSI-LD.\nIf another attribute is is to be used, an additional `geoproperty` parameter is required.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." - }, - "response": [] } ], - "description": "# Architecture\n\nThe demo application will send and receive NGSI-LD calls to a compliant context broker. Since both NSGI v2 and NSGI-LD\ninterfaces are available to an experimental version fo the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/), our demo application will only make use of one\nFIWARE component.\n\nCurrently, the Orion Context Broker relies on open source [MongoDB](https://www.mongodb.com/) technology to keep\npersistence of the context data it holds. Therefore, the architecture will consist of two elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using\n [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the Orion Context Broker to hold context data information such as data entities, subscriptions and\n registrations\n\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.\n\n![](https://fiware.github.io/tutorials.Linked-Data/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of the associated `docker-compose.yml` file:\n\n```yaml\norion:\n image: fiware/orion-ld\n hostname: orion\n container_name: fiware-orion\n depends_on:\n - mongo-db\n networks:\n - default\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n healthcheck:\n test: curl --fail -s http://orion:1026/version || exit 1\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --nojournal\n```\n\nBoth containers are residing on the same network - the Orion Context Broker is listening on Port `1026` and MongoDB is\nlistening on the default port `27071`. Both containers are also exposing the same ports externally - this is purely for\nthe tutorial access - so that cUrl or Postman can access them without being part of the same network. The command-line\ninitialization should be self explanatory.\n\nThe only notable difference to the introductory tutorials is that the required image name is currently\n`fiware/orion-ld`.\n\n# Start Up\n\nAll services can be initialised from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.Linked-Data/blob/master/services) Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:\n\n```bash\ngit clone git@github.com:FIWARE/tutorials.Linked-Data.git\ncd tutorials.Linked-Data\n\n./services scorpio\n```\n\n\n> **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n> ```\n> ./services stop\n> ```\n", + "description": "# Architecture\n\nThe demo application will send and receive NGSI-LD calls to a compliant context broker. Since both NSGI v2 and NSGI-LD\ninterfaces are available to an experimental version fo the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/), our demo application will only make use of one\nFIWARE component.\n\nCurrently, the Orion Context Broker relies on open source [MongoDB](https://www.mongodb.com/) technology to keep\npersistence of the context data it holds. Therefore, the architecture will consist of two elements:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) which will receive requests using\n [NGSI-LD](https://forge.etsi.org/swagger/ui/?url=https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/spec/updated/full_api.json)\n- The underlying [MongoDB](https://www.mongodb.com/) database :\n - Used by the Orion Context Broker to hold context data information such as data entities, subscriptions and\n registrations\n\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.\n\n![](https://fiware.github.io/tutorials.Linked-Data/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of the associated `docker-compose.yml` file:\n\n```yaml\norion:\n image: fiware/orion-ld\n hostname: orion\n container_name: fiware-orion\n depends_on:\n - mongo-db\n networks:\n - default\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n healthcheck:\n test: curl --fail -s http://orion:1026/version || exit 1\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --nojournal\n```\n\nBoth containers are residing on the same network - the Orion Context Broker is listening on Port `1026` and MongoDB is\nlistening on the default port `27071`. Both containers are also exposing the same ports externally - this is purely for\nthe tutorial access - so that cUrl or Postman can access them without being part of the same network. The command-line\ninitialization should be self explanatory.\n\nThe only notable difference to the introductory tutorials is that the required image name is currently\n`fiware/orion-ld`.\n\n# Start Up\n\nAll services can be initialised from the command-line by running the\n[services](https://github.com/FIWARE/tutorials.Linked-Data/blob/master/services) Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:\n\n```bash\ngit clone git@github.com:FIWARE/tutorials.Linked-Data.git\ncd tutorials.Linked-Data\n\n./services orion\n```\n\n\n> **Note:** If you want to clean up and start over again you can do so with the following command:\n>\n> ```\n> ./services stop\n> ```\n", "event": [ { "listen": "prerequest", @@ -1007,457 +55,27 @@ ] }, { - "name": "Linked Data using Stellio", + "name": "Linked Data using Scorpio", "item": [ { - "name": "Obtain full Linked Data model context", + "name": "Obtaining Version Information", "request": { "method": "GET", "header": [], "url": { - "raw": "{{datamodels-context.jsonld}}", - "host": [ - "{{datamodels-context.jsonld}}" - ] - }, - "description": "Information about the data models and relationships used within this tutorial\ncan be obtained by requesting the full `@context` and `@graph`." - }, - "response": [] - }, - { - "name": "Creating your first Data Entity", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Type", - "value": "application/ld+json" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"Property\",\n \"value\": [\"commercial\"]\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Bornholmer Straße 65\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Prenzlauer Berg\",\n \"postalCode\": \"10439\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3986, 52.5547]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Bösebrücke Einkauf\"\n },\n \"@context\": [\n \"https://smartdatamodels.org/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\"\n ]\n}" - }, - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ] - }, - "description": "## Creating Context Data\n\nWhen creating linked data entities, it is important to use common data models. This will allow us to easily combine data\nfrom multiple sources and remove ambiguity when comparing data coming from different sources.\n\nCreating linked data using full qualified names throughout would be painful, as each attribute would need to be a URN,\nso JSON-LD introduces the idea of an `@context` attribute which can hold pointers to context definitions. To add a\nFIWARE [Building](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html) data entity,\nthe following `@context` would be required\n\n```json\n{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n ... other data attributes\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\n### Core Context\n\n[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld)\nrefers to the Core `@context` of NSGI-LD, this defines element such as `id` and `type` which are common to all NGSI\nentities, as well as defining terms such as `Property` and `Relationship`. The core context is so fundamental to\nNGSI-LD, that it is added by default to any `@context` sent to a request.\n\n### FIWARE Data Models\n\n[https://smartdatamodels.org/context.jsonld](https://smartdatamodels.org/context.jsonld)\nrefers to the definition of standard data models supplied by FIWARE. Adding this to the `@context` will load the\ndefinitions of all the [data models](https://fiware-datamodels.readthedocs.io) defined by the FIWARE Foundation, a\nsummary of the FQNs related to **Building** can be seen below:\n\n```json\n{\n \"@context\": {\n \"Building\": \"https://uri.fiware.org/ns/datamodels/Building\",\n ... etc\n \"address\": \"http://schema.org/address\",\n \"category\": \"https://uri.fiware.org/ns/datamodels/category\",\n \"location\": \"http://uri.etsi.org/ngsi-ld/location\",\n \"name\": \"http://schema.org/name\",\n ...etc\n }\n}\n```\n\nIf we include this context definition, it means that we will be able to use short names for `Building`, `address`,\n`location` for our entities, but computers will also be able to read the FNQs when comparing with other sources.\n\nTo create a valid **Building** data entity in the context broker, make a POST request to the\n`http://localhost:1026/ngsi-ld/v1/entities` endpoint as shown below. It is essential that the appropriate\n`Content-Type: application/ld+json` is also used, so that the data entity is recognized as Linked data.\n\nThe first request will take some time, as the context broker must navigate and load all of the files mentioned in the\n`@context`.\n\n\n> **Note**: if `https://smartdatamodels.org/context.jsonld` is unavailable for some reason the request will fail\n>\n> For a working production system it is essential that the `@context` files are always available to ensure third parties can\n> read the context. High availability infrastructure has not been considered for this tutorial to keep the architecture simple." - }, - "response": [] - }, - { - "name": "Creating your Second Data Entity", - "request": { - "method": "POST", - "header": [ - { - "key": "Content-Type", - "value": "application/ld+json" - } - ], - "body": { - "mode": "raw", - "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store002\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"Property\",\n \"value\": [\"commercial\"]\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Friedrichstraße 44\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Kreuzberg\",\n \"postalCode\": \"10969\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3903, 52.5075]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Checkpoint Markt\"\n },\n \"@context\": [\n \"https://smartdatamodels.org/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\"\n ]\n}" - }, - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ] - }, - "description": "Each subsequent entity must have a unique `id` for the given `type`.\n\n### Defining Properties within the NGSI-LD entity definition\n\nThe attributes `id` and `type` should be familiar to anyone who has used NSGI v2, and these have not changed. As\nmentioned above, the type should refer to an included data model, in this case `Building` is being used as a short name\nfor the inclued URN `https://uri.fiware.org/ns/datamodels/Building`. Thereafter each _property_ is defined as a JSON\nelement containing two attributes, a `type` and a `value`.\n\nThe `type` of a _property_ attribute must be one of the following:\n\n- `\"GeoProperty\"`: `\"http://uri.etsi.org/ngsi-ld/GeoProperty\"` for locations. Locations should be specified as\n Longitude-Latitude pairs in [GeoJSON format](https://tools.ietf.org/html/rfc7946). The preferred name for the\n primary location attribute is `location`\n- `\"TemporalProperty\"`: `\"http://uri.etsi.org/ngsi-ld/TemporalProperty\"` for time-based values. Temporal properties\n should be Date, Time or DateTime strings encoded be [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - e.g.\n `YYYY-MM-DDThh:mm:ssZ`\n- `\"Property\"`: `\"http://uri.etsi.org/ngsi-ld/Property\"` - for everything else\n\n> **Note:** that for simplicity, this data entity has no relationships defined. Relationships must be given the\n> `type=\"Relationship`. Relationships will be discusssed in a subsequent tutorial.\n\n### Defining Properties-of-Properties within the NGSI-LD entity definition\n\n_Properties-of-Properties_ is the NGSI-LD equivalent of metadata (i.e. _\"data about data\"_), it is use to describe\nproperties of the attribute value itself like accuracy, provider, or the units to be used. Some built-in metadata\nattributes already exist and these names are reserved:\n\n- `createdAt` (type: DateTime): attribute creation date as an ISO 8601 string.\n- `modifiedAt` (type: DateTime): attribute modification date as an ISO 8601 string.\n\nAdditionally `observedAt`, `datasetId` and `instanceId` may optionally be added in some cases, and `location`,\n`observationSpace` and `operationSpace` have special meaning for Geoproperties.\n\nIn the examples given above, one element of metadata (i.e. a _property-of-a-property_) can be found within the `address`\nattribute. a `verified` flag indicates whether the address has been confirmed. The commonest _property-of-a-property_ is\n`unitCode` which should be used to hold the UN/CEFACT\n[Common Codes](http://wiki.goodrelations-vocabulary.org/Documentation/UN/CEFACT_Common_Codes) for Units of Measurement." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by FNQ type", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", - "disabled": true - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities?type=https://uri.fiware.org/ns/data-models%23Building", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities" - ], - "query": [ - { - "key": "type", - "value": "https://uri.fiware.org/ns/data-models%23Building" - } - ] - }, - "description": "This example returns the data of all `Building` entities within the context data The `type` parameter is mandatory for\nNGSI-LD and is used to filter the response.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible.\n\n- `id`, `type` and `location` are defined in the core context and are not expanded.\n- `address` has been mapped to `http://schema.org/address`\n- `name` has been mapped to `http://schema.org/name`\n- `category` has been mapped to `https://uri.fiware.org/ns/datamodels#category`\n\nNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\n**always** be displayed." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by id", - "request": { - "method": "GET", - "header": [ - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "urn:ngsi-ld:Building:store001" - ], - "query": [ - { - "key": "type", - "value": "Store", - "description": "Entity type, to avoid ambiguity in case there are several entities with the same entity id", - "disabled": true - }, - { - "key": "attrs", - "value": "name", - "description": "Ordered list of attribute names to display", - "disabled": true - } - ] - }, - "description": "This example returns the data of `urn:ngsi-ld:Building:store001`.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible." - }, - "response": [] - }, - { - "name": "Obtain Entity Data by type and linked context", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities?type=Building&options=keyValues", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "If a reference to the supplied data is supplied, it is possible to return short name data and limit responses to a\nspecific `type` of data. For example, the request below returns the data of all `Building` entities within the context\ndata. Use of the `type` parameter limits the response to `Building` entities only, use of the `options=keyValues` query\nparameter reduces the response down to standard JSON-LD.\n\nA [`Link` header](https://www.w3.org/wiki/LinkHeader) must be supplied to associate the short form `type=\"Building\"`\nwith the FNQ `https://uri.fiware.org/ns/datamodels/Building`. The full link header syntax can be seen below:\n\n```text\nLink: ; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\n```\n\nThe standard HTTP `Link` header allows metadata (in this case the `@context`) to be passed in without actually touching\nthe resource in question. In the case of NGSI-LD, the metadata is a file of in `application/ld+json` format.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute defintions\n`type=\"Property\"` or any _properties-of-properties_ elements. You can see that `Link` header from the request has been\nused as the `@context` returned in the response." - }, - "response": [] - }, - { - "name": "Filter context data by attribute value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/?type=Building&q=name==\"Checkpoint Markt\"&options=keyValues", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "name==\"Checkpoint Markt\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns all `Building` entiies with the `name` attribute _Checkpoint Markt_. Filtering can be done using\nthe `q` parameter - if a string has spaces in it, it can be URL encoded and held within single quote characters `'` =\n`%27`.\n\nThe `Link` header `https://smartdatamodels.org/context.jsonld` holds an array of `@context` as shown:\n\n```json\n{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\nand therefore includes the FIWARE Building model.\n\nThis means that use of the `Link` header and the `options=keyValues` parameter reduces the response to short form\nJSON-LD as shown:" - }, - "response": [] - }, - { - "name": "Filter context data by attribute in an Array", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text", - "name": "Accept" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/?type=Building&q=category==\"commercial\",\"office\"&options=keyValues", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "category==\"commercial\",\"office\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "Within the standard `Building` model, the `category` attribute refers to an array of strings. This example returns all\n`Building` entities with a `category` attribute which contains either `commercial` or `office` strings. Filtering can be\ndone using the `q` parameter, comma separating the acceptable values.\n\nThe response is returned in JSON-LD format with short form attribute names" - }, - "response": [] - }, - { - "name": "Filter context data by sub-attribute value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/?type=Building&q=address%5BaddressLocality%5D==\"Kreuzberg\"&options=keyValues", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "address%5BaddressLocality%5D==\"Kreuzberg\"" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns all stores found in the Kreuzberg District.\n\nFiltering can be done using the `q` parameter - sub-attributes are annotated using the bracket syntax e.g.\n`q=address[addressLocality]==Kreuzberg`. This differs from NGSI v2 where dot syntax was used.\n\nUse of the `Link` header and the `options=keyValues` parameter reduces the response to JSON-LD." - }, - "response": [] - }, - { - "name": "Filter context data by metadata value", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/?type=Building&q=address.verified==true&options=keyValues", - "protocol": "http", - "host": [ - "{{stellio}}" - ], - "path": [ - "ngsi-ld", - "v1", - "entities", - "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "q", - "value": "address.verified==true" - }, - { - "key": "options", - "value": "keyValues", - "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" - } - ] - }, - "description": "This example returns the data of all `Building` entities with a verified address. The `verified` attribute is an example\nof a _Property-of-a-Property_\n\nMetadata queries (i.e. Properties of Properties) are annotated using the dot syntax e.g. `q=address.verified==true`.\nThis supercedes the `mq` parameter from NGSI v2.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." - }, - "response": [] - }, - { - "name": "Filter context data by distance", - "request": { - "method": "GET", - "header": [ - { - "key": "Link", - "type": "text", - "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" - }, - { - "key": "Accept", - "value": "application/ld+json", - "type": "text" - } - ], - "url": { - "raw": "http://{{stellio}}/ngsi-ld/v1/entities/?type=Building&geometry=Point&coordinates=%5B13.3777,52.5162%5D&georel=near;maxDistance==2000&options=keyValues", + "raw": "http://{{scorpio}}/scorpio/v1/info/", "protocol": "http", "host": [ - "{{stellio}}" + "{{scorpio}}" ], "path": [ - "ngsi-ld", + "scorpio", "v1", - "entities", + "info", "" - ], - "query": [ - { - "key": "type", - "value": "Building" - }, - { - "key": "geometry", - "value": "Point" - }, - { - "key": "coordinates", - "value": "%5B13.3777,52.5162%5D" - }, - { - "key": "georel", - "value": "near;maxDistance==2000", - "description": "Ordered list of attribute names to display" - }, - { - "key": "options", - "value": "keyValues" - } ] }, - "description": "This example return all Stores within 2km the **Brandenburg Gate** in **Berlin** (_52.5162N 13.3777W_). To make a\ngeo-query request, three parameters must be specified, `geometry`, `coordinates` and `georel`.\n\nThe syntax for NGSI-LD has been updated, the `coordinates` parameter is now represented in\n[geoJSON](https://tools.ietf.org/html/rfc7946) including the square brackets rather than the simple lat-long pairs\nrequired in NGSI v2.\n\nNote that by default the geo-query will be applied to the `location` attribute, as this is default specified in NGSI-LD.\nIf another attribute is is to be used, an additional `geoproperty` parameter is required.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." + "description": "This tutorial recreates the same data entities as the intial _\"Powered by FIWARE\"_ supermarket finder app, but using\nNGSI-LD linked data entities rather than NGSI v2.\n\n## Checking the service health\n\nAs usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.\n\nThe format of the response has not changed. The `release_date` must be 16th July 2019 or later to be able to\nwork with the requests defined below." }, "response": [] } @@ -1483,6 +101,468 @@ } } ] + }, + { + "name": "Obtain full Linked Data model context", + "request": { + "method": "GET", + "header": [], + "url": { + "raw": "{{datamodels-context.jsonld}}", + "host": [ + "{{datamodels-context.jsonld}}" + ] + }, + "description": "Information about the data models and relationships used within this tutorial\ncan be obtained by requesting the full `@context` and `@graph`." + }, + "response": [] + }, + { + "name": "Creating your first Data Entity", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/ld+json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"VocabularyProperty\",\n \"vocab\": \"commercial\"\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Bornholmer Straße 65\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Prenzlauer Berg\",\n \"postalCode\": \"10439\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3986, 52.5547]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Bösebrücke Einkauf\"\n },\n \"@context\": [\n \"https://smart-data-models.github.io/dataModel.Building/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld\"\n ]\n}" + }, + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ] + }, + "description": "## Creating Context Data\n\nWhen creating linked data entities, it is important to use common data models. This will allow us to easily combine data\nfrom multiple sources and remove ambiguity when comparing data coming from different sources.\n\nCreating linked data using full qualified names throughout would be painful, as each attribute would need to be a URN,\nso JSON-LD introduces the idea of an `@context` attribute which can hold pointers to context definitions. To add a\nFIWARE [Building](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html) data entity,\nthe following `@context` would be required\n\n```json\n{\n \"id\": \"urn:ngsi-ld:Building:store001\",\n \"type\": \"Building\",\n ... other data attributes\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\n### Core Context\n\n[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld)\nrefers to the Core `@context` of NSGI-LD, this defines element such as `id` and `type` which are common to all NGSI\nentities, as well as defining terms such as `Property` and `Relationship`. The core context is so fundamental to\nNGSI-LD, that it is added by default to any `@context` sent to a request.\n\n### FIWARE Data Models\n\n[https://smartdatamodels.org/context.jsonld](https://smartdatamodels.org/context.jsonld)\nrefers to the definition of standard data models supplied by FIWARE. Adding this to the `@context` will load the\ndefinitions of all the [data models](https://fiware-datamodels.readthedocs.io) defined by the FIWARE Foundation, a\nsummary of the FQNs related to **Building** can be seen below:\n\n```json\n{\n \"@context\": {\n \"Building\": \"https://uri.fiware.org/ns/datamodels/Building\",\n ... etc\n \"address\": \"http://schema.org/address\",\n \"category\": \"https://uri.fiware.org/ns/datamodels/category\",\n \"location\": \"http://uri.etsi.org/ngsi-ld/location\",\n \"name\": \"http://schema.org/name\",\n ...etc\n }\n}\n```\n\nIf we include this context definition, it means that we will be able to use short names for `Building`, `address`,\n`location` for our entities, but computers will also be able to read the FNQs when comparing with other sources.\n\nTo create a valid **Building** data entity in the context broker, make a POST request to the\n`http://localhost:1026/ngsi-ld/v1/entities` endpoint as shown below. It is essential that the appropriate\n`Content-Type: application/ld+json` is also used, so that the data entity is recognized as Linked data.\n\nThe first request will take some time, as the context broker must navigate and load all of the files mentioned in the\n`@context`.\n\n\n> **Note**: if `https://smartdatamodels.org/context.jsonld` is unavailable for some reason the request will fail\n>\n> For a working production system it is essential that the `@context` files are always available to ensure third parties can\n> read the context. High availability infrastructure has not been considered for this tutorial to keep the architecture simple." + }, + "response": [] + }, + { + "name": "Creating your Second Data Entity", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "value": "application/ld+json" + } + ], + "body": { + "mode": "raw", + "raw": "{\n \"id\": \"urn:ngsi-ld:Building:store002\",\n \"type\": \"Building\",\n \"category\": {\n \t\"type\": \"VocabularyProperty\",\n \"vocab\": \"commercial\"\n },\n \"address\": {\n \"type\": \"Property\",\n \"value\": {\n \"streetAddress\": \"Friedrichstraße 44\",\n \"addressRegion\": \"Berlin\",\n \"addressLocality\": \"Kreuzberg\",\n \"postalCode\": \"10969\"\n },\n \"verified\": {\n\t\t\t\"type\": \"Property\",\n\t\t\t\"value\": true\n\t\t}\n },\n \"location\": {\n \"type\": \"GeoProperty\",\n \"value\": {\n \"type\": \"Point\",\n \"coordinates\": [13.3903, 52.5075]\n }\n },\n \"name\": {\n \"type\": \"Property\",\n \"value\": \"Checkpoint Markt\"\n },\n \"@context\": [\n \"https://smart-data-models.github.io/dataModel.Building/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld\"\n ]\n}" + }, + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ] + }, + "description": "Each subsequent entity must have a unique `id` for the given `type`.\n\n### Defining Properties within the NGSI-LD entity definition\n\nThe attributes `id` and `type` should be familiar to anyone who has used NSGI v2, and these have not changed. As\nmentioned above, the type should refer to an included data model, in this case `Building` is being used as a short name\nfor the inclued URN `https://uri.fiware.org/ns/datamodels/Building`. Thereafter each _property_ is defined as a JSON\nelement containing two attributes, a `type` and a `value`.\n\nThe `type` of a _property_ attribute must be one of the following:\n\n- `\"GeoProperty\"`: `\"http://uri.etsi.org/ngsi-ld/GeoProperty\"` for locations. Locations should be specified as\n Longitude-Latitude pairs in [GeoJSON format](https://tools.ietf.org/html/rfc7946). The preferred name for the\n primary location attribute is `location`\n- `\"TemporalProperty\"`: `\"http://uri.etsi.org/ngsi-ld/TemporalProperty\"` for time-based values. Temporal properties\n should be Date, Time or DateTime strings encoded be [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - e.g.\n `YYYY-MM-DDThh:mm:ssZ`\n- `\"Property\"`: `\"http://uri.etsi.org/ngsi-ld/Property\"` - for everything else\n\n> **Note:** that for simplicity, this data entity has no relationships defined. Relationships must be given the\n> `type=\"Relationship`. Relationships will be discusssed in a subsequent tutorial.\n\n### Defining Properties-of-Properties within the NGSI-LD entity definition\n\n_Properties-of-Properties_ is the NGSI-LD equivalent of metadata (i.e. _\"data about data\"_), it is use to describe\nproperties of the attribute value itself like accuracy, provider, or the units to be used. Some built-in metadata\nattributes already exist and these names are reserved:\n\n- `createdAt` (type: DateTime): attribute creation date as an ISO 8601 string.\n- `modifiedAt` (type: DateTime): attribute modification date as an ISO 8601 string.\n\nAdditionally `observedAt`, `datasetId` and `instanceId` may optionally be added in some cases, and `location`,\n`observationSpace` and `operationSpace` have special meaning for Geoproperties.\n\nIn the examples given above, one element of metadata (i.e. a _property-of-a-property_) can be found within the `address`\nattribute. a `verified` flag indicates whether the address has been confirmed. The commonest _property-of-a-property_ is\n`unitCode` which should be used to hold the UN/CEFACT\n[Common Codes](http://wiki.goodrelations-vocabulary.org/Documentation/UN/CEFACT_Common_Codes) for Units of Measurement." + }, + "response": [] + }, + { + "name": "Obtain Entity Data by FNQ type", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", + "disabled": true + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities?type=https://smartdatamodels.org/dataModel.Building/Building", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities" + ], + "query": [ + { + "key": "type", + "value": "https://smartdatamodels.org/dataModel.Building/Building" + } + ] + }, + "description": "This example returns the data of all `Building` entities within the context data The `type` parameter is mandatory for\nNGSI-LD and is used to filter the response.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible.\n\n- `id`, `type` and `location` are defined in the core context and are not expanded.\n- `address` has been mapped to `http://schema.org/address`\n- `name` has been mapped to `http://schema.org/name`\n- `category` has been mapped to `https://uri.fiware.org/ns/datamodels#category`\n\nNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\n**always** be displayed." + }, + "response": [] + }, + { + "name": "Obtain Entity Data by id", + "request": { + "method": "GET", + "header": [ + { + "key": "Accept", + "value": "application/ld+json", + "type": "text" + }, + { + "key": "Link", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"", + "type": "text", + "disabled": true + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001?options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "urn:ngsi-ld:Building:store001" + ], + "query": [ + { + "key": "type", + "value": "Store", + "description": "Entity type, to avoid ambiguity in case there are several entities with the same entity id", + "disabled": true + }, + { + "key": "attrs", + "value": "name", + "description": "Ordered list of attribute names to display", + "disabled": true + }, + { + "key": "options", + "value": "keyValues" + } + ] + }, + "description": "This example returns the data of `urn:ngsi-ld:Building:store001`.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible." + }, + "response": [] + }, + { + "name": "Obtain Entity Data by type and linked context", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text", + "name": "Accept" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities?type=Building&options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities" + ], + "query": [ + { + "key": "type", + "value": "Building" + }, + { + "key": "options", + "value": "keyValues", + "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" + } + ] + }, + "description": "If a reference to the supplied data is supplied, it is possible to return short name data and limit responses to a\nspecific `type` of data. For example, the request below returns the data of all `Building` entities within the context\ndata. Use of the `type` parameter limits the response to `Building` entities only, use of the `options=keyValues` query\nparameter reduces the response down to standard JSON-LD.\n\nA [`Link` header](https://www.w3.org/wiki/LinkHeader) must be supplied to associate the short form `type=\"Building\"`\nwith the FNQ `https://uri.fiware.org/ns/datamodels/Building`. The full link header syntax can be seen below:\n\n```text\nLink: ; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\n```\n\nThe standard HTTP `Link` header allows metadata (in this case the `@context`) to be passed in without actually touching\nthe resource in question. In the case of NGSI-LD, the metadata is a file of in `application/ld+json` format.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute defintions\n`type=\"Property\"` or any _properties-of-properties_ elements. You can see that `Link` header from the request has been\nused as the `@context` returned in the response." + }, + "response": [] + }, + { + "name": "Filter context data by attribute value", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text", + "name": "Accept" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/?type=Building&q=name==\"Checkpoint Markt\"&options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ], + "query": [ + { + "key": "type", + "value": "Building" + }, + { + "key": "q", + "value": "name==\"Checkpoint Markt\"" + }, + { + "key": "options", + "value": "keyValues", + "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" + } + ] + }, + "description": "This example returns all `Building` entiies with the `name` attribute _Checkpoint Markt_. Filtering can be done using\nthe `q` parameter - if a string has spaces in it, it can be URL encoded and held within single quote characters `'` =\n`%27`.\n\nThe `Link` header `https://smartdatamodels.org/context.jsonld` holds an array of `@context` as shown:\n\n```json\n{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld\",\n \"https://smartdatamodels.org/context.jsonld\"\n ]\n}\n```\n\nand therefore includes the FIWARE Building model.\n\nThis means that use of the `Link` header and the `options=keyValues` parameter reduces the response to short form\nJSON-LD as shown:" + }, + "response": [] + }, + { + "name": "Filter context data by attribute in an Array", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text", + "name": "Accept" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/?type=Building&q=category==\"commercial\",\"office\"&options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ], + "query": [ + { + "key": "type", + "value": "Building" + }, + { + "key": "q", + "value": "category==\"commercial\",\"office\"" + }, + { + "key": "options", + "value": "keyValues", + "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" + } + ] + }, + "description": "Within the standard `Building` model, the `category` attribute refers to an array of strings. This example returns all\n`Building` entities with a `category` attribute which contains either `commercial` or `office` strings. Filtering can be\ndone using the `q` parameter, comma separating the acceptable values.\n\nThe response is returned in JSON-LD format with short form attribute names" + }, + "response": [] + }, + { + "name": "Filter context data by sub-attribute value", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/?type=Building&q=address%5BaddressLocality%5D==\"Kreuzberg\"&options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ], + "query": [ + { + "key": "type", + "value": "Building" + }, + { + "key": "q", + "value": "address%5BaddressLocality%5D==\"Kreuzberg\"" + }, + { + "key": "options", + "value": "keyValues", + "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" + } + ] + }, + "description": "This example returns all stores found in the Kreuzberg District.\n\nFiltering can be done using the `q` parameter - sub-attributes are annotated using the bracket syntax e.g.\n`q=address[addressLocality]==Kreuzberg`. This differs from NGSI v2 where dot syntax was used.\n\nUse of the `Link` header and the `options=keyValues` parameter reduces the response to JSON-LD." + }, + "response": [] + }, + { + "name": "Filter context data by metadata value", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/?type=Building&q=address.verified==true&options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ], + "query": [ + { + "key": "type", + "value": "Building" + }, + { + "key": "q", + "value": "address.verified==true" + }, + { + "key": "options", + "value": "keyValues", + "description": "* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values `attrs` for an ordered list of attributes only" + } + ] + }, + "description": "This example returns the data of all `Building` entities with a verified address. The `verified` attribute is an example\nof a _Property-of-a-Property_\n\nMetadata queries (i.e. Properties of Properties) are annotated using the dot syntax e.g. `q=address.verified==true`.\nThis supercedes the `mq` parameter from NGSI v2.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." + }, + "response": [] + }, + { + "name": "Filter context data by distance", + "request": { + "method": "GET", + "header": [ + { + "key": "Link", + "type": "text", + "value": "<{{datamodels-context.jsonld}}>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" + }, + { + "key": "Accept", + "value": "application/ld+json", + "type": "text" + } + ], + "url": { + "raw": "http://{{context-broker}}/ngsi-ld/v1/entities/?type=Building&geometry=Point&coordinates=%5B13.3777,52.5162%5D&georel=near;maxDistance==2000&options=keyValues", + "protocol": "http", + "host": [ + "{{context-broker}}" + ], + "path": [ + "ngsi-ld", + "v1", + "entities", + "" + ], + "query": [ + { + "key": "type", + "value": "Building" + }, + { + "key": "geometry", + "value": "Point" + }, + { + "key": "coordinates", + "value": "%5B13.3777,52.5162%5D" + }, + { + "key": "georel", + "value": "near;maxDistance==2000", + "description": "Ordered list of attribute names to display" + }, + { + "key": "options", + "value": "keyValues" + } + ] + }, + "description": "This example return all Stores within 2km the **Brandenburg Gate** in **Berlin** (_52.5162N 13.3777W_). To make a\ngeo-query request, three parameters must be specified, `geometry`, `coordinates` and `georel`.\n\nThe syntax for NGSI-LD has been updated, the `coordinates` parameter is now represented in\n[geoJSON](https://tools.ietf.org/html/rfc7946) including the square brackets rather than the simple lat-long pairs\nrequired in NGSI v2.\n\nNote that by default the geo-query will be applied to the `location` attribute, as this is default specified in NGSI-LD.\nIf another attribute is is to be used, an additional `geoproperty` parameter is required.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and\n`metadata` elements." + }, + "response": [] } ], "event": [ @@ -1507,23 +587,13 @@ ], "variable": [ { - "key": "orion", + "key": "context-broker", "value": "localhost:1026", "type": "string" }, { "key": "datamodels-context.jsonld", - "value": "https://smartdatamodels.org/context.jsonld", - "type": "string" - }, - { - "key": "scorpio", - "value": "localhost:9090", - "type": "string" - }, - { - "key": "stellio", - "value": "localhost:8080", + "value": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "type": "string" } ] diff --git a/README.ja.md b/README.ja.md index 41c52bb..283e38e 100644 --- a/README.ja.md +++ b/README.ja.md @@ -387,7 +387,7 @@ curl -X GET \ Smart Data [Building](https://github.com/smart-data-models/dataModel.Building) データ・エンティティを追加するには、次の `@context` が必要です。 -```jsonld +```json { "id": "urn:ngsi-ld:Building:store001", "type": "Building", @@ -414,13 +414,13 @@ Smart Data [Building](https://github.com/smart-data-models/dataModel.Building) FIWARE Foundation によって定義されたすべての[データモデル](https://smartdatamodels.org/)の定義が読み込まれます。 **Building** に関連する FQNs の概要は以下のようになります : -```jsonld +```json { "@context": { "Building": "https://uri.fiware.org/ns/dataModels#Building", ... etc "address": "http://schema.org/address", - "category": "https://uri.fiware.org/ns/dataModels#category", + "category": "https://smart-data-models.github.io/data-models/terms.jsonld#/definitions/category", "location": "https://uri.etsi.org/ngsi-ld/location", "name": "https://uri.etsi.org/ngsi-ld/name", ...etc @@ -442,7 +442,7 @@ FIWARE Foundation によって定義されたすべての[データモデル](ht NGSI-LD [Core @context](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld) を使用する場合、 -```jsonld +```json { "@context": { "ngsi-ld": "https://uri.etsi.org/ngsi-ld/", @@ -475,8 +475,8 @@ curl -iX POST \ "id": "urn:ngsi-ld:Building:store001", "type": "Building", "category": { - "type": "Property", - "value": ["commercial"] + "type": "VocabularyProperty", + "vocab": "commercial" }, "address": { "type": "Property", @@ -533,8 +533,8 @@ curl -iX POST \ "id": "urn:ngsi-ld:Building:store002", "type": "Building", "category": { - "type": "Property", - "value": ["commercial"] + "type": "VocabularyProperty", + "vocab": "commercial" }, "address": { "type": "Property", @@ -641,11 +641,11 @@ curl -G -X GET \ - `id`, `type`, `location`, `name` はコア・コンテキストで定義されており、展開されません - `address` は `http://schema.org/address` にマッピングされました -- `category` は `https://uri.fiware.org/ns/dataModels#category` にマッピングされました +- `category` は `https://smart-data-models.github.io/data-models/terms.jsonld#/definitions/category` にマッピングされました エンティティの作成時に属性が FQN に関連付けられていない場合は、短い名前が**常**に表示されます。 -```jsonld +```json [ { "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld", @@ -668,9 +668,9 @@ curl -G -X GET \ "type": "Property", "value": "Bösebrücke Einkauf" }, - "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "https://uri.fiware.org/ns/dataModels#commercial" + "https://smart-data-models.github.io/data-models/terms.jsonld#/definitions/category": { + "type": "VocabularyProperty", + "vocab": "https://uri.fiware.org/ns/dataModels#commercial" }, "location": { "type": "GeoProperty", @@ -704,9 +704,9 @@ curl -G -X GET \ "type": "Property", "value": "Checkpoint Markt" }, - "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "https://uri.fiware.org/ns/dataModels#commercial" + "https://smart-data-models.github.io/data-models/terms.jsonld#/definitions/category": { + "type": "VocabularyProperty", + "vocab": "https://uri.fiware.org/ns/dataModels#commercial" }, "location": { "type": "GeoProperty", @@ -742,7 +742,7 @@ curl -G -X GET \ (`https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld`) で コアの `@context` を返し、すべての属性は可能な限り展開されます。 -```jsonld +```json { "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld", "id": "urn:ngsi-ld:Building:store001", @@ -764,9 +764,9 @@ curl -G -X GET \ "type": "Property", "value": "Bösebrücke Einkauf" }, - "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "https://uri.fiware.org/ns/dataModels#commercial" + "https://smart-data-models.github.io/data-models/terms.jsonld#/definitions/category": { + "type": "VocabularyProperty", + "vocab": "https://uri.fiware.org/ns/dataModels#commercial" }, "location": { "type": "GeoProperty", @@ -819,7 +819,7 @@ curl -G -X GET \ _properties-of-properties_ 要素は含まれていません。リクエストからの `Link` ヘッダはレスポンスに返される `@context` として使われていることがわかります。 -```jsonld +```json [ { "@context": "https://fiware.github.io/data-models/context.jsonld", @@ -832,7 +832,9 @@ _properties-of-properties_ 要素は含まれていません。リクエスト "postalCode": "10439" }, "name": "Bösebrücke Einkauf", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -852,7 +854,9 @@ _properties-of-properties_ 要素は含まれていません。リクエスト "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -888,7 +892,7 @@ curl -G -X GET \ `Link` ヘッダ `https://schema.lab.fiware.org/ld/context` は以下に示すように `@context` の配列を保持します : -```jsonld +```json { "@context": [ "https://fiware.github.io/data-models/context.jsonld", @@ -902,7 +906,7 @@ curl -G -X GET \ これは、`Link` ヘッダと `options=keyValues` パラメータを使用すると、以下に示すように短い形式の JSON-LD へのレスポンスが減ることを意味します : -```jsonld +```json [ { "@context": "https://fiware.github.io/data-models/context.jsonld", @@ -915,7 +919,9 @@ curl -G -X GET \ "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -951,7 +957,7 @@ curl -G -X GET \ レスポンスは、短い形式の属性名を使用してJSON-LD 形式で返されます : -```jsonld +```json [ { "@context": "https://fiware.github.io/data-models/context.jsonld", @@ -964,7 +970,9 @@ curl -G -X GET \ "postalCode": "10439" }, "name": "Bösebrücke Einkauf", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -984,7 +992,9 @@ curl -G -X GET \ "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -1021,7 +1031,7 @@ curl -G -X GET \ `Link` ヘッダと `options=keyValues` パラメータの使用は JSON-LD へのレスポンスを減らします。 -```jsonld +```json [ { "@context": "https://fiware.github.io/data-models/context.jsonld", @@ -1034,7 +1044,9 @@ curl -G -X GET \ "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -1073,7 +1085,7 @@ curl -G -X GET \ Accept HTTP ヘッダと一緒に `options=keyValues` を使用しているため、レスポンスは属性 `type` と `metadata` 要素のない JSON のみで構成されています。 -```jsonld +```json [ { "@context": "https://fiware.github.io/data-models/context.jsonld", @@ -1086,7 +1098,9 @@ Accept HTTP ヘッダと一緒に `options=keyValues` を使用しているた "postalCode": "10439" }, "name": "Bösebrücke Einkauf", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -1106,7 +1120,9 @@ Accept HTTP ヘッダと一緒に `options=keyValues` を使用しているた "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ @@ -1150,7 +1166,7 @@ curl -G -X GET \ Accept HTTP ヘッダと一緒に `options=keyValues` を使用しているため、レスポンスは属性 `type` と `metadata` 要素のない JSON のみで構成されています。 -```jsonld +```json [ { "@context": "https://fiware.github.io/data-models/context.jsonld", @@ -1163,7 +1179,9 @@ Accept HTTP ヘッダと一緒に `options=keyValues` を使用しているた "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [ diff --git a/README.md b/README.md index e565e53..2846961 100644 --- a/README.md +++ b/README.md @@ -353,12 +353,12 @@ so JSON-LD introduces the idea of an `@context` attribute which can hold pointer Data [Building](https://github.com/smart-data-models/dataModel.Building) data entity, the following `@context` would be required -```jsonld +```json { "id": "urn:ngsi-ld:Building:store001", "type": "Building", ... other data attributes - "@context": "https://fiware.github.io/data-models/context.jsonld" + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld" } ``` @@ -372,40 +372,43 @@ NGSI-LD, that it is added by default to any `@context` sent to a request. ### Smart Data Models -[https://schema.lab.fiware.org/ld/context](https://schema.lab.fiware.org/ld/context) refers to the definition of -standard data models supplied by FIWARE. Adding this to the `@context` will load the definitions of all the -[data models](https://smartdatamodels.org/) defined by the FIWARE Foundation in collaboration with other organizations +[https://smart-data-models.github.io/dataModel.Building/context.jsonld](https://schema.lab.fiware.org/ld/context) refers to a User `@context` - a definition of +a standard data models. Adding this to the `@context` will load a common definition of a **Building** +[data model](https://smartdatamodels.org/) defined by the FIWARE Foundation in collaboration with other organizations such as GSMA or TM Forum. A summary of the FQNs related to **Building** can be seen below: -```jsonld +```json { "@context": { - "Building": "https://uri.fiware.org/ns/dataModels#Building", + "Building": "https://smartdatamodels.org/dataModel.Building/Building", ... etc - "address": "http://schema.org/address", - "category": "https://uri.fiware.org/ns/dataModels#category", - "location": "https://uri.etsi.org/ngsi-ld/location", - "name": "https://uri.etsi.org/ngsi-ld/name", + + "address": "https://smartdatamodels.org/address", + "addressCountry": "https://smartdatamodels.org/addressCountry", + "addressLocality": "https://smartdatamodels.org/addressLocality", + "addressRegion": "https://smartdatamodels.org/addressRegion", + "category": "https://smartdatamodels.org/dataModel.Building/category", + "name": "https://smartdatamodels.org/name", ...etc } } ``` If we include this context definition, it means that we will be able to use short names for `Building`, `address`, -`location` for our entities, but computers will also be able to read the FQNs when comparing with other sources. +`name` for our entities, but computers will also be able to read the FQNs when comparing with other sources. #### Context terms are IRIs not URLs It should be noted that According to the [JSON-LD Spec](https://www.w3.org/TR/json-ld/#the-context) : _"a context is used to map terms to IRIs."_ - An IRI (Internationalized Resource Identifier) is not necessarily a URL - see [here](https://fusion.cs.uni-jena.de/fusion/blog/2016/11/18/iri-uri-url-urn-and-their-differences/) and therefore it is -not unexpected if elements such as `https://uri.etsi.org/ngsi-ld/name` do not actually resolve to a web page. However +not unexpected if elements such as `https://smartdatamodels.org/name` do not actually resolve to a web page. However many IRIs within JSON-LD `@context` files, such as `http://schema.org/address` do indeed return web pages with more information about themselves. If you take the NGSI-LD [Core @context](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld) -```jsonld +```json { "@context": { @@ -433,14 +436,14 @@ To create a valid **Building** data entity in the context broker, make a POST re ```console curl -iX POST \ - http://localhost:1026/ngsi-ld/v1/entities \ + 'http://localhost:1026/ngsi-ld/v1/entities' \ -H 'Content-Type: application/ld+json' \ -d '{ "id": "urn:ngsi-ld:Building:store001", "type": "Building", "category": { - "type": "Property", - "value": ["commercial"] + "type": "VocabularyProperty", + "vocab": "commercial" }, "address": { "type": "Property", @@ -467,7 +470,7 @@ curl -iX POST \ "value": "Bösebrücke Einkauf" }, "@context": [ - "https://fiware.github.io/data-models/context.jsonld", + "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" ] }' @@ -477,7 +480,7 @@ The first request will take some time, as the context broker must navigate and l `@context`. > [!NOTE] -> if `https://fiware.github.io/data-models/context.jsonld` is unavailable for some reason the request will +> if `https://smart-data-models.github.io/dataModel.Building/context.jsonld` is unavailable for some reason the request will > fail > > For a working production system it is essential that the `@context` files are always available to ensure third parties @@ -496,8 +499,8 @@ curl -iX POST \ "id": "urn:ngsi-ld:Building:store002", "type": "Building", "category": { - "type": "Property", - "value": ["commercial"] + "type": "VocabularyProperty", + "vocab": "commercial" }, "address": { "type": "Property", @@ -524,7 +527,7 @@ curl -iX POST \ "value": "Checkpoint Markt" }, "@context": [ - "https://fiware.github.io/data-models/context.jsonld", + "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" ] }' @@ -542,13 +545,15 @@ The `type` of a _property_ attribute must be one of the following: - `"GeoProperty"`: `"http://uri.etsi.org/ngsi-ld/GeoProperty"` for locations. Locations should be specified as Longitude-Latitude pairs in [GeoJSON format](https://tools.ietf.org/html/rfc7946). The preferred name for the primary location attribute is `location` +- `"VocabularyProperty"` holds enumerated values and is a mapping of a URI to a value within the user'`@context` +- `"LanguageProperty"` holds a set of internationalized strings. - `"Property"`: `"http://uri.etsi.org/ngsi-ld/Property"` - for everything else. - For time-based values, `"Property"` shall be used as well, but the property value should be Date, Time or DateTime strings encoded in the [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - e.g. `YYYY-MM-DDThh:mm:ssZ` > [!NOTE] > Note that for simplicity, this data entity has no relationships defined. Relationships must be given the -> `type=Relationship`. Relationships will be discussed in a subsequent tutorial. +> `type=Relationship` or one of its defined subtypes. Relationships will be discussed in a subsequent tutorial. ### Defining Properties-of-Properties within the NGSI-LD entity definition @@ -584,7 +589,7 @@ NGSI-LD and is used to filter the response. The Accept HTTP header is needed to curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ -H 'Accept: application/ld+json' \ - -d 'type=https%3A%2F%2Furi.fiware.org%2Fns%2Fdata-models%23Building' + -d 'type=https%3A%2F%2Fsmartdatamodels.org%2FdataModel.Building%2FBuilding' ``` #### Response: @@ -592,20 +597,25 @@ curl -G -X GET \ The response returns the Core `@context` by default (`https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld`) and all attributes are expanded whenever possible. -- `id`, `type`, `location` and `name`are defined in the core context and are not expanded. -- `address` has been mapped to `http://schema.org/address` -- `category` has been mapped to `https://uri.fiware.org/ns/dataModels#category` +- `id`, `type` and `location` are defined in the core context and are not expanded. +- `address` has been mapped to `http://smartdatamodels.org/address` +- `name` has been mapped to `http://smartdatamodels.org/name` +- `category` has been mapped to `https://smartdatamodels.org/dataModel.Building/category` Note that if an attribute has not been not associated to an FQN when the entity was created, the short name will -**always** be displayed. +**always** be displayed - `verified` and `commercial` are examples of this since they were missing from the supplied user `@context` when inserting the context data. -```jsonld +```json [ { "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld", "id": "urn:ngsi-ld:Building:store001", - "type": "https://uri.fiware.org/ns/dataModels#Building", - "https://schema.org/address": { + "type": "https://smartdatamodels.org/dataModel.Building/Building", + "https://smartdatamodels.org/dataModel.Building/category": { + "type": "VocabularyProperty", + "vocab": "commercial" + }, + "https://smartdatamodels.org/address": { "type": "Property", "value": { "streetAddress": "Bornholmer Straße 65", @@ -618,53 +628,55 @@ Note that if an attribute has not been not associated to an FQN when the entity "value": true } }, - "https://uri.etsi.org/ngsi-ld/name": { - "type": "Property", - "value": "Bösebrücke Einkauf" - }, - "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "https://uri.fiware.org/ns/dataModels#commercial" - }, "location": { "type": "GeoProperty", "value": { "type": "Point", - "coordinates": [13.3986, 52.5547] + "coordinates": [ + 13.3986, + 52.5547 + ] } + }, + "https://smartdatamodels.org/name": { + "type": "Property", + "value": "Bösebrücke Einkauf" } }, { "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld", "id": "urn:ngsi-ld:Building:store002", - "type": "https://uri.fiware.org/ns/dataModels#Building", - "https://schema.org/address": { + "type": "https://smartdatamodels.org/dataModel.Building/Building", + "https://smartdatamodels.org/dataModel.Building/category": { + "type": "VocabularyProperty", + "vocab": "commercial" + }, + "https://smartdatamodels.org/address": { "type": "Property", "value": { - "streetAddress": "Friedrichstraße 44", - "addressRegion": "Berlin", - "addressLocality": "Kreuzberg", - "postalCode": "10969" + "https://smartdatamodels.org/streetAddress": "Friedrichstraße 44", + "https://smartdatamodels.org/addressRegion": "Berlin", + "https://smartdatamodels.org/addressLocality": "Kreuzberg", + "https://smartdatamodels.org/postalCode": "10969" }, "verified": { "type": "Property", "value": true } }, - "https://uri.etsi.org/ngsi-ld/name": { - "type": "Property", - "value": "Checkpoint Markt" - }, - "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "https://uri.fiware.org/ns/dataModels#commercial" - }, "location": { "type": "GeoProperty", "value": { "type": "Point", - "coordinates": [13.3903, 52.5075] + "coordinates": [ + 13.3903, + 52.5075 + ] } + }, + "https://smartdatamodels.org/name": { + "type": "Property", + "value": "Checkpoint Markt" } } ] @@ -687,39 +699,28 @@ curl -G -X GET \ The response returns the Core `@context` by default (`https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld`) and all attributes are expanded whenever possible. -```jsonld +```json { "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld", "id": "urn:ngsi-ld:Building:store001", - "type": "https://uri.fiware.org/ns/dataModels#Building", - "https://schema.org/address": { - "type": "Property", - "value": { - "streetAddress": "Bornholmer Straße 65", - "addressRegion": "Berlin", - "addressLocality": "Prenzlauer Berg", - "postalCode": "10439" - }, - "verified": { - "type": "Property", - "value": true - } + "type": "https://smartdatamodels.org/dataModel.Building/Building", + "https://smartdatamodels.org/dataModel.Building/category": { + "vocab": "commercial" }, - "https://uri.etsi.org/ngsi-ld/name": { - "type": "Property", - "value": "Bösebrücke Einkauf" - }, - "https://uri.fiware.org/ns/dataModels#category": { - "type": "Property", - "value": "https://uri.fiware.org/ns/dataModels#commercial" + "https://smartdatamodels.org/address": { + "streetAddress": "Bornholmer Straße 65", + "addressRegion": "Berlin", + "addressLocality": "Prenzlauer Berg", + "postalCode": "10439" }, "location": { - "type": "GeoProperty", - "value": { - "type": "Point", - "coordinates": [13.3986, 52.5547] - } - } + "type": "Point", + "coordinates": [ + 13.3986, + 52.5547 + ] + }, + "https://smartdatamodels.org/name": "Bösebrücke Einkauf" } ``` @@ -734,7 +735,7 @@ A [`Link` header](https://www.w3.org/wiki/LinkHeader) must be supplied to associ with the FQN `https://uri.fiware.org/ns/data-models/Building`. The full link header syntax can be seen below: ```text -Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json +Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json ``` The standard HTTP `Link` header allows metadata (in this case the `@context`) to be passed in without actually touching @@ -745,7 +746,7 @@ the resource in question. In the case of NGSI-LD, the metadata is a file in `app ```console curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ - -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ + -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ -H 'Accept: application/ld+json' \ -d 'type=Building' \ -d 'options=keyValues' @@ -757,10 +758,10 @@ Because of the use of the `options=keyValues`, the response consists of JSON onl `type="Property"` or any _properties-of-properties_ elements. You can see that `Link` header from the request has been used as the `@context` returned in the response. -```jsonld +```json [ { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store001", "type": "Building", "address": { @@ -770,14 +771,16 @@ used as the `@context` returned in the response. "postalCode": "10439" }, "name": "Bösebrücke Einkauf", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3986, 52.5547] } }, { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store002", "type": "Building", "address": { @@ -787,7 +790,9 @@ used as the `@context` returned in the response. "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3903, 52.5075] @@ -807,7 +812,7 @@ the `q` parameter - if a string has spaces in it, it can be URL encoded and held ```console curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ - -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ + -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ -H 'Accept: application/ld+json' \ -d 'type=Building' \ -d 'q=name==%22Checkpoint%20Markt%22' \ @@ -816,26 +821,15 @@ curl -G -X GET \ #### Response: -The `Link` header `https://schema.lab.fiware.org/ld/context` holds an array of `@context` as shown: - -```jsonld -{ - "@context": [ - "https://fiware.github.io/data-models/context.jsonld", - "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.6.jsonld" - ] -} -``` - -and therefore includes the FIWARE Building model. +The `Link` header `https://smart-data-models.github.io/dataModel.Building/context.jsonld` includes the FIWARE Building model. This means that use of the `Link` header and the `options=keyValues` parameter reduces the response to short form JSON-LD as shown: -```jsonld +```json [ { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store002", "type": "Building", "address": { @@ -845,7 +839,9 @@ JSON-LD as shown: "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3903, 52.5075] @@ -856,30 +852,37 @@ JSON-LD as shown: ### Filter context data by comparing the values of an attribute in an Array -Within the standard `Building` model, the `category` attribute refers to an array of strings. This example returns all +Within the standard `Building` model, the `category` attribute refers to an array of enumerated strings. This example returns all `Building` entities with a `category` attribute which contains either `commercial` or `office` strings. Filtering can be done using the `q` parameter, comma separating the acceptable values. +> [!NOTE] +> +> `category` has been defined as a **VocabularyProperty**, which would usually mean that the `vocab` +> value should be a URI defined in the `@context`. The `expandValues` hint indicates that URI +> expansion is required for the `category` attribute when querying the context data. + #### 8️⃣ Request: ```console curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ - -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ + -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ -H 'Accept: application/ld+json' \ -d 'type=Building' \ -d 'q=category==%22commercial%22,%22office%22' \ - -d 'options=keyValues' + -d 'options=keyValues' \ + -d 'expandValues=category' ``` #### Response: The response is returned in JSON-LD format with short form attribute names: -```jsonld +```json [ { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store001", "type": "Building", "address": { @@ -889,14 +892,16 @@ The response is returned in JSON-LD format with short form attribute names: "postalCode": "10439" }, "name": "Bösebrücke Einkauf", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3986, 52.5547] } }, { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store002", "type": "Building", "address": { @@ -906,7 +911,9 @@ The response is returned in JSON-LD format with short form attribute names: "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3903, 52.5075] @@ -927,7 +934,7 @@ Filtering can be done using the `q` parameter - sub-attributes are annotated usi ```console curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ - -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ + -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ -H 'Accept: application/ld+json' \ -d 'type=Building' \ -d 'q=address%5BaddressLocality%5D==%22Kreuzberg%22' \ @@ -938,10 +945,10 @@ curl -G -X GET \ Use of the `Link` header and the `options=keyValues` parameter reduces the response to JSON-LD. -```jsonld +```json [ { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store002", "type": "Building", "address": { @@ -951,7 +958,9 @@ Use of the `Link` header and the `options=keyValues` parameter reduces the respo "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3903, 52.5075] @@ -973,7 +982,7 @@ This supersedes the `mq` parameter from NGSI v2. ```console curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ - -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ + -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ -H 'Accept: application/json' \ -d 'type=Building' \ -d 'q=address.verified==true' \ @@ -985,10 +994,10 @@ curl -G -X GET \ Because of the use of the `options=keyValues` together with the Accept HTTP header (`application/json`), the response consists of JSON only without the attribute `type` and `metadata` elements. -```jsonld +```json [ { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store001", "type": "Building", "address": { @@ -998,14 +1007,16 @@ consists of JSON only without the attribute `type` and `metadata` elements. "postalCode": "10439" }, "name": "Bösebrücke Einkauf", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3986, 52.5547] } }, { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store002", "type": "Building", "address": { @@ -1015,7 +1026,9 @@ consists of JSON only without the attribute `type` and `metadata` elements. "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3903, 52.5075] @@ -1041,7 +1054,7 @@ If another attribute is to be used, an additional `geoproperty` parameter is req ```console curl -G -X GET \ 'http://localhost:1026/ngsi-ld/v1/entities' \ - -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ + -H 'Link: ; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \ -H 'Accept: application/json' \ -d 'type=Building' \ -d 'geometry=Point' \ @@ -1055,10 +1068,10 @@ curl -G -X GET \ Because of the use of the `options=keyValues` together with the Accept HTTP header (`application/json`), the response consists of JSON only without the attribute `type` and `metadata` elements. -```jsonld +```json [ { - "@context": "https://fiware.github.io/data-models/context.jsonld", + "@context": "https://smart-data-models.github.io/dataModel.Building/context.jsonld", "id": "urn:ngsi-ld:Building:store002", "type": "Building", "address": { @@ -1068,7 +1081,9 @@ consists of JSON only without the attribute `type` and `metadata` elements. "postalCode": "10969" }, "name": "Checkpoint Markt", - "category": "commercial", + "category": { + "vocab" :"commercial" + }, "location": { "type": "Point", "coordinates": [13.3903, 52.5075] @@ -1081,4 +1096,4 @@ consists of JSON only without the attribute `type` and `metadata` elements. ## License -[MIT](LICENSE) © 2019-2020 FIWARE Foundation e.V. +[MIT](LICENSE) © 2019-2024 FIWARE Foundation e.V. diff --git a/docker-compose/orion-ld.yml b/docker-compose/orion-ld.yml index 6763627..ca2abfa 100644 --- a/docker-compose/orion-ld.yml +++ b/docker-compose/orion-ld.yml @@ -31,7 +31,7 @@ services: - default ports: - "${EXPOSED_PORT}:${ORION_LD_PORT}" # localhost:1026 - command: -dbhost mongo-db -logLevel DEBUG -forwarding + command: -dbhost mongo-db -logLevel DEBUG -experimental healthcheck: test: curl --fail -s http://orion:${ORION_LD_PORT}/version || exit 1 interval: 5s