![\"GitHub\"](\"https://fiware.github.io/tutorials.Linked-Data/icon/GitHub-Mark-32px.png\"){kind=icon}
FIWARE 601: Linked DataThis tutorial introduces linked data concepts to the FIWARE Platform. The supermarket chain’s store finder application\nis recreated using NGSI-LD the differences between the NSGI v2 and NGSI-LD interfaces are highlighted and\ndiscussed. The tutorial is a direct analogue of the original getting started tutorial but uses API calls from the\nNGSI-LD interface.
\nThe docker-compose files for this tutorial can be found on GitHub:
\n\n“Six degrees of separation doesn't mean that everyone is linked to everyone else in just six steps. It means that a\nvery small number of people are linked to everyone else in a few steps, and the rest of us are linked to the world\nthrough those special few.”
\n― Malcolm Gladwell, The Tipping Point
\n
The introduction to FIWARE Getting Started tutorial introduced\nthe NSGI v2 interface that is commonly used to create and\nmanipulate context data entities. An evolution of that interface has created a supplementary specification called\nNGSI-LD\nas a mechanism to enhance context data entities though adding the concept of linked data. This tutorial will\nintroduce the background of the ideas behind the new interface and compare and contrast how to create and manipulate\ndata entites as linked data.
\nAddtional tutorials in the series will further discuss data relationships an how to create context data entities using\nlinked data enabling the full knowledge graph to be traversed.
\nAll users of the Internet will be familiar with the concept of hypertext links, the way that a link on one web page is\nable to guide the browser to loading another page from a known location.
\nWhilst humans are able to understand relationship discoverability and how links work, computers find this much more\ndifficult, and require a well-defined protocol to be able to traverse from one data element to another held in a\nseparate location.
\nCreating a system of readable links for computers requires the use of a well defined data format\n(JSON-LD) and assignation of unique IDs\n(URLs or URNs) for both\ndata entities and the relationships between entities so that semantic meaning can be programmatically retrieved from the\ndata itself.
\nProperly defined linked data can be used to help answer big data questions, and the data relationships can be traversed\nto answer questions like \"Which products are currently avaiable on the shelves of Store X and what prices are they sold\nat?\"
\n![\"\"](\"http://img.youtube.com/vi/4x_xzT5eF5Q/0.jpg\")
Click on the image above to watch an introductory video on linked data concepts
\nJSON-LD is an extension of JSON , it is a standard way of avoiding ambiguity when expressing linked data in JSON so that\nthe data is structured in a format which is parsable by machines. It is a method of ensuring that all data attributes\ncan be easily compared when coming from a multitude of separate data sources, which could have a different idea as to\nwhat each attribute means. For example, when two data entities have a name attribute how can the computer be certain\nthat is refers to a \"Name of a thing\" in the same sense (rather than a Username or a Surname or something).\nURLs and datamodels are used to remove ambiguity by allowing attributes to have a both short form (such as name) and a\nfully specified long form (such http://schema.org/name) which means it is easy to discover which attribute have a\ncommon meaning within a data structure.
JSON-LD introduces the concept of the @context element which provides additional information allowing the computer to\ninterpret the rest of the data with more clarity and depth.
Furthermore the JSON-LD specification enables you to define a unique @type associating a well-defined\ndata model to the data itself.
![\"\"](\"http://img.youtube.com/vi/vioCbTo3C-4/0.jpg\")
Click on the image above to watch a video describing the basic concepts behind JSON-LD.
\nNGSI-LD is an evolution of the NGSI v2 information model, which has been modified to improve support for linked\ndata (entity relationships), property graphs and semantics (exploiting the capabilities offered by JSON-LD). This work\nhas been conducted under the ETSI ISG CIM initiative and the updated specification hhas been branded as\nNGSI-LD. The main constructs\nof NGSI-LD are: Entity, Property and Relationship. NGSI-LD Entities (instances) can be the subject of Properties\nor Relationships. In terms of the traditional NGSI v2 data model, Properties can be seen as the combination of an\nattribute and its value. Relationships allow to establish associations between instances using linked data.
\nAs a reminder, the NGSI v2 data model is quite simple. It can be summarized as shown below:
\n![\"\"](\"https://fiware.github.io/tutorials.Linked-Data/img/ngsi-v2.png\")
The core element of NGSI v2 is the data entity, typically a real object with a changing state (such as a Store, a\nShelf and so on). Entities have attributes (such as name and location) and these in turn hold metadata such\nas accuracy - i.e. the accuracy of a location reading.
Every entity must have a type which defines the sort of thing the entity describes, but giving an NGSI v2 entity the\ntype=Store is relatively meaningless as no-one is obliged to shape their own Store entities in the same fashion.\nSimilarly adding an attribute called name doesn't suddenly make it hold the same data as someone else's name\nattribute.
Relationships can be defined using NGSI v2, but only so far as giving the attribute an appropriate attribute name\ndefined by convention ( e.g. starting with ref, such as refManagedBy) and assigning the attribute\ntype=Relationship which again is purely a naming convention with no real semantic weight.
The NGSI LD data model is more complex, with more rigid definitions of use which lead to a navigable knowledge graph.
\n![\"\"](\"https://fiware.github.io/tutorials.Linked-Data/img/ngsi-ld.png\")
Once again, entity can be considered to be the core element. Every entity must use a unique id\nURN, there is also a type, used to define the structure of the\ndata held, which is also a URN. This URN should correspond to a well-defined data model which can be found on the web.\nFor example the URN https://uri.fiware.org/ns/datamodels/Building is used to define common data model for a\nBuilding.
Entities can have properties and relationships. Ideally the name of each property should also be a well defined\nURN which corresponds to a common concept found across the web (e.g. http://schema.org/address is a common URN for the\nphysical address of an item). The property will also have a value which will reflect the state of that property (e.g\nname=\"Checkpoint Markt\"). Finally a property may itself have further properties (a.k.a. properties-of-properties)\nwhich reflect further information about the property itself. Properties and relationships may in turn have a linked\nembedded structure (of properties-of-properties or properties-of-relationships or relationships-of-properties or\nrelationships-of-relationships etc.) which lead to the following:
An NGSI LD Data Entity (e.g. a supermarket):
\nid which must be unique. For example urn:ngsi-ld:Building:store001,type which should be a fully qualified URN of a well defined data model. For example\nhttps://uri.fiware.org/ns/datamodels#Buildingaddress attribute which holds the adress of the store. This can be\nexpanded into http://schema.org/address, which is known as a fully qualified name\n(FQN).address, like any property will have a value corresponding to the property address (e.g. Bornholmer\nStraße 65, 10439 Prenzlauer Berg, Berlinverified field for the address.managedBy field where the relationship managedBy corresponds\nto another data entity : urn:ngsi-ld:Person:bob-the-managermanagedBy, may itself have a property-of-a-relationship (e.g. since), this holds the date Bob\nstarted working the storemanagedBy, may itself have a relationship-of-a-relationship (e.g. subordinateTo), this holds\nthe URN of the area manager above Bob in the hierarchy.As you can see the knowledge graph is well defined and can be expanded indefinitely.
\nRelationships will be dealt with in more detail in a subsequent tutorial.
\nTo keep things simple all components will be run using Docker. Docker is a container\ntechnology which allows to different components isolated into their respective environments.
\nDocker Compose is a tool for defining and running multi-container Docker applications. A\nYAML file is used\nconfigure the required services for the application. This means all container services can be brought up in a single\ncommand. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users\nwill need to follow the instructions found here
\nWe will start up our services using a simple bash script. Windows users should download cygwin\nto provide a command-line functionality similar to a Linux distribution on Windows.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Adding Linked Data concepts to FIWARE Data Entities.","slug":"adding-linked-data-concepts-to-fiware-data-entities"},{"content":"Prerequisites","slug":"prerequisites"}],"owner":"513743","collectionId":"8f9fb52f-f756-439f-984c-b9d273376f4b","publishedId":"SVYjSMgh","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"4C4C4C","highlight":"233C68"},"publishDate":"2020-01-02T11:02:01.000Z"},"item":[{"name":"Linked Data using Orion-LD","item":[{"name":"Obtaining Version Information","id":"fe6c3057-27ca-446f-bd10-f459b1bc4dac","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://localhost:1026/version/","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.
\nAs usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.
\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.
Information about the data models and relationships used within this tutorial\ncan be obtained by requesting the full @context and @graph.
When 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.
\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 data entity,\nthe following @context would be required
{\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.jsonld\",\n \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n ]\n}\nhttps://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.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.
https://schema.lab.fiware.org/ld/fiware-datamodels-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 defined by the FIWARE Foundation, a\nsummary of the FQNs related to Building can be seen below:
{\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}\nIf we include this context definition, it means that we will be able to use short names for Building, address,\nlocation for our entities, but computers will also be able to read the FNQs when comparing with other sources.
To create a valid Building data entity in the context broker, make a POST request to the\nhttp://localhost:1026/ngsi-ld/v1/entities endpoint as shown below. It is essential that the appropriate\nContent-Type: application/ld+json is also used, so that the data entity is recognized as Linked data.
The 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","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities",""],"host":["localhost:1026"],"query":[],"variable":[]}},"response":[],"_postman_id":"3f85285d-31d9-4c32-82eb-dbbf1469d3c8"},{"name":"Creating your Second Data Entity","id":"85c473a7-b4cd-4a14-b3ce-f7b0e0ce31bb","protocolProfileBehavior":{"disableBodyPruning":true},"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://fiware.github.io/data-models/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\"\n ]\n}"},"url":"http://localhost:1026/ngsi-ld/v1/entities/","description":"Note: if
\nhttps://fiware.github.io/data-models/context.jsonldis unavailable for some reason the request will failFor a working production system it is essential that the
\n@contextfiles are always available to ensure third parties can\nread the context. High availability infrastructure has not been considered for this tutorial to keep the architecture simple.
Each subsequent entity must have a unique id for the given type.
The 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.
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\nLongitude-Latitude pairs in GeoJSON format. The preferred name for the\nprimary location attribute is location\"TemporalProperty\": \"http://uri.etsi.org/ngsi-ld/TemporalProperty\" for time-based values. Temporal properties\nshould be Date, Time or DateTime strings encoded be ISO 8601 format - e.g.\nYYYY-MM-DDThh:mm:ssZ\"Property\": \"http://uri.etsi.org/ngsi-ld/Property\" - for everything else\n\nNote: that for simplicity, this data entity has no relationships defined. Relationships must be given the\n
\ntype=\"Relationship. Relationships will be discusssed in a subsequent tutorial.
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:
\ncreatedAt (type: DateTime): attribute creation date as an ISO 8601 string.modifiedAt (type: DateTime): attribute modification date as an ISO 8601 string.Additionally observedAt, datasetId and instanceId may optionally be added in some cases, and location,\nobservationSpace and operationSpace have special meaning for Geoproperties.
In 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\nunitCode which should be used to hold the UN/CEFACT\nCommon Codes for Units of Measurement.
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.
The 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.
id, type and location are defined in the core context and are not expanded.address has been mapped to http://schema.org/addressname has been mapped to http://schema.org/namecategory has been mapped to https://uri.fiware.org/ns/datamodels#categoryNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\nalways be displayed.
\n","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities"],"host":["localhost:1026"],"query":[{"key":"type","value":"https://uri.fiware.org/ns/data-models%23Building"}],"variable":[]}},"response":[],"_postman_id":"f2dbfcd7-2144-47b2-89d3-00cce8bce30c"},{"name":"Obtain Entity Data by id","id":"9105db02-fb83-4e36-90ef-54196c719334","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/ld+json","type":"text"}],"url":"http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001","description":"This example returns the data of urn:ngsi-ld:Building:store001.
The 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.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"9105db02-fb83-4e36-90ef-54196c719334"},{"name":"Obtain Entity Data by type and linked context","id":"09634a0a-7ee2-460e-9870-d2437818f615","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","type":"text","value":"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.
A Link header 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:
Link: <https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\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.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute defintions\ntype=\"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.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis 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.
The Link header https://schema.lab.fiware.org/ld/context holds an array of @context as shown:
{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\",\n \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n ]\n}\nand therefore includes the FIWARE Building model.
\nThis means that use of the Link header and the options=keyValues parameter reduces the response to short form\nJSON-LD as shown:
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyWithin the standard Building model, the category attribute refers to an array of strings. This example returns all\nBuilding 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.
The response is returned in JSON-LD format with short form attribute names
\n","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities",""],"host":["localhost:1026"],"query":[{"key":"type","value":"Building"},{"key":"q","value":"category==\"commercial\",\"office\""},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns all stores found in the Kreuzberg District.
\nFiltering can be done using the q parameter - sub-attributes are annotated using the bracket syntax e.g.\nq=address[addressLocality]==Kreuzberg. This differs from NGSI v2 where dot syntax was used.
Use of the Link header and the options=keyValues parameter reduces the response to JSON-LD.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns the data of all Building entities with a verified address. The verified attribute is an example\nof a Property-of-a-Property
Metadata 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.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute type and\nmetadata elements.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis 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.
The syntax for NGSI-LD has been updated, the coordinates parameter is now represented in\ngeoJSON including the square brackets rather than the simple lat-long pairs\nrequired in NGSI v2.
Note 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.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute type and\nmetadata elements.
Ordered list of attribute names to display
\n","type":"text/plain"},"key":"georel","value":"near;maxDistance==2000"},{"key":"options","value":"keyValues"}],"variable":[]}},"response":[],"_postman_id":"c6454020-2f49-4c34-8f0a-ec36df0fc16e"}],"id":"284f5126-93d0-4bd7-b2db-fc61473589d4","description":"The 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\nOrion Context Broker, our demo application will only make use of one\nFIWARE component.
\nCurrently, the Orion Context Broker relies on open source MongoDB technology to keep\npersistence of the context data it holds. Therefore, the architecture will consist of two elements:
\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.
\n![](\"https://fiware.github.io/tutorials.Linked-Data/img/architecture.png\")
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file:
orion:\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\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\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.
The only notable difference to the introductory tutorials is that the required image name is currently\nfiware/orion-ld.
All services can be initialised from the command-line by running the\nservices Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:
\ngit clone git@github.com:FIWARE/tutorials.Linked-Data.git\ncd tutorials.Linked-Data\n\n./services orion\n\n\n","event":[{"listen":"prerequest","script":{"id":"c6f208cc-a59b-42b8-9620-62d9ef03ae93","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"b83a80ad-cdaa-46cb-86c8-33cd8ab776a0","type":"text/javascript","exec":[""]}}],"_postman_id":"284f5126-93d0-4bd7-b2db-fc61473589d4"},{"name":"Linked Data using Scorpio","item":[{"name":"Obtaining Version Information","id":"e089f828-7ff9-43ee-b9a7-7115989d62dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://localhost:9090/scorpio/v1/info/","description":"Note: If you want to clean up and start over again you can do so with the following command:
\n./services stop\n
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.
\nAs usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.
\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.
Information about the data models and relationships used within this tutorial\ncan be obtained by requesting the full @context and @graph.
When 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.
\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 data entity,\nthe following @context would be required
{\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.jsonld\",\n \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n ]\n}\nhttps://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.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.
https://schema.lab.fiware.org/ld/fiware-datamodels-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 defined by the FIWARE Foundation, a\nsummary of the FQNs related to Building can be seen below:
{\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}\nIf we include this context definition, it means that we will be able to use short names for Building, address,\nlocation for our entities, but computers will also be able to read the FNQs when comparing with other sources.
To create a valid Building data entity in the context broker, make a POST request to the\nhttp://localhost:1026/ngsi-ld/v1/entities endpoint as shown below. It is essential that the appropriate\nContent-Type: application/ld+json is also used, so that the data entity is recognized as Linked data.
The 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","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities",""],"host":["localhost:9090"],"query":[],"variable":[]}},"response":[],"_postman_id":"4610cae2-db40-493f-9610-9d36758daa6d"},{"name":"Creating your Second Data Entity","id":"2ae054eb-b13f-4b73-91c8-0ec7e462d09c","protocolProfileBehavior":{"disableBodyPruning":true},"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://fiware.github.io/data-models/context.jsonld\",\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\"\n ]\n}"},"url":"http://localhost:9090/ngsi-ld/v1/entities/","description":"Note: if
\nhttps://fiware.github.io/data-models/context.jsonldis unavailable for some reason the request will failFor a working production system it is essential that the
\n@contextfiles are always available to ensure third parties can\nread the context. High availability infrastructure has not been considered for this tutorial to keep the architecture simple.
Each subsequent entity must have a unique id for the given type.
The 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.
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\nLongitude-Latitude pairs in GeoJSON format. The preferred name for the\nprimary location attribute is location\"TemporalProperty\": \"http://uri.etsi.org/ngsi-ld/TemporalProperty\" for time-based values. Temporal properties\nshould be Date, Time or DateTime strings encoded be ISO 8601 format - e.g.\nYYYY-MM-DDThh:mm:ssZ\"Property\": \"http://uri.etsi.org/ngsi-ld/Property\" - for everything else\n\nNote: that for simplicity, this data entity has no relationships defined. Relationships must be given the\n
\ntype=\"Relationship. Relationships will be discusssed in a subsequent tutorial.
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:
\ncreatedAt (type: DateTime): attribute creation date as an ISO 8601 string.modifiedAt (type: DateTime): attribute modification date as an ISO 8601 string.Additionally observedAt, datasetId and instanceId may optionally be added in some cases, and location,\nobservationSpace and operationSpace have special meaning for Geoproperties.
In 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\nunitCode which should be used to hold the UN/CEFACT\nCommon Codes for Units of Measurement.
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.
The 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.
id, type and location are defined in the core context and are not expanded.address has been mapped to http://schema.org/addressname has been mapped to http://schema.org/namecategory has been mapped to https://uri.fiware.org/ns/datamodels#categoryNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\nalways be displayed.
\n","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities"],"host":["localhost:9090"],"query":[{"key":"type","value":"https://uri.fiware.org/ns/data-models%23Building"}],"variable":[]}},"response":[],"_postman_id":"76b8e6dd-a2e2-4e3c-8a41-1281ace0ae42"},{"name":"Obtain Entity Data by id","id":"081b277b-cfc0-4605-8406-3e6869448235","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/ld+json","type":"text"}],"url":"http://localhost:9090/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001","description":"This example returns the data of urn:ngsi-ld:Building:store001.
The 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.
Entity type, to avoid ambiguity in case there are several entities with the same entity id
\n","type":"text/plain"},"key":"type","value":"Store"},{"disabled":true,"description":{"content":"Ordered list of attribute names to display
\n","type":"text/plain"},"key":"attrs","value":"name"}],"variable":[]}},"response":[],"_postman_id":"081b277b-cfc0-4605-8406-3e6869448235"},{"name":"Obtain Entity Data by type and linked context","id":"865b5f65-30d8-4f7d-b4ae-b07cccef37bb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","type":"text","value":"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.
A Link header 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:
Link: <https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\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.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute defintions\ntype=\"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.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis 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.
The Link header https://schema.lab.fiware.org/ld/context holds an array of @context as shown:
{\n \"@context\": [\n \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\",\n \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n ]\n}\nand therefore includes the FIWARE Building model.
\nThis means that use of the Link header and the options=keyValues parameter reduces the response to short form\nJSON-LD as shown:
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyWithin the standard Building model, the category attribute refers to an array of strings. This example returns all\nBuilding 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.
The response is returned in JSON-LD format with short form attribute names
\n","urlObject":{"protocol":"http","path":["ngsi-ld","v1","entities",""],"host":["localhost:9090"],"query":[{"key":"type","value":"Building"},{"key":"q","value":"category==\"commercial\",\"office\""},{"description":{"content":"keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns all stores found in the Kreuzberg District.
\nFiltering can be done using the q parameter - sub-attributes are annotated using the bracket syntax e.g.\nq=address[addressLocality]==Kreuzberg. This differs from NGSI v2 where dot syntax was used.
Use of the Link header and the options=keyValues parameter reduces the response to JSON-LD.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis example returns the data of all Building entities with a verified address. The verified attribute is an example\nof a Property-of-a-Property
Metadata 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.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute type and\nmetadata elements.
keyValues option in order to get a more compact and brief representation, including just attribute valuesvalues option combined with a list of attribute values attrs for an ordered list of attributes onlyThis 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.
The syntax for NGSI-LD has been updated, the coordinates parameter is now represented in\ngeoJSON including the square brackets rather than the simple lat-long pairs\nrequired in NGSI v2.
Note 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.
Because of the use of the options=keyValues, the response consists of JSON only without the attribute type and\nmetadata elements.
Ordered list of attribute names to display
\n","type":"text/plain"},"key":"georel","value":"near;maxDistance==2000"},{"key":"options","value":"keyValues"}],"variable":[]}},"response":[],"_postman_id":"79ee8f5f-4905-43fa-8970-f589506c340b"}],"id":"bd97c44e-2303-47b2-87ef-976f85a6638e","description":"The 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\nOrion Context Broker, our demo application will only make use of one\nFIWARE component.
\nCurrently, the Orion Context Broker relies on open source MongoDB technology to keep\npersistence of the context data it holds. Therefore, the architecture will consist of two elements:
\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and\nrun from exposed ports.
\n
The necessary configuration information can be seen in the services section of the associated docker-compose.yml file:
orion:\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\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\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.
The only notable difference to the introductory tutorials is that the required image name is currently\nfiware/orion-ld.
All services can be initialised from the command-line by running the\nservices Bash script provided within the\nrepository. Please clone the repository and create the necessary images by running the commands as shown:
\ngit clone git@github.com:FIWARE/tutorials.Linked-Data.git\ncd tutorials.Linked-Data\n\n./services scorpio\n\n\n","event":[{"listen":"prerequest","script":{"id":"83da53ad-eed6-4bc8-baf1-28dae04deb58","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"8b5bbd87-a1a9-4a07-864e-aebff7afa941","type":"text/javascript","exec":[""]}}],"_postman_id":"bd97c44e-2303-47b2-87ef-976f85a6638e"}],"event":[{"listen":"prerequest","script":{"id":"581cc060-de73-4283-915a-fcaa1c126830","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5215414e-418f-4c32-8070-b68d62c90ea4","type":"text/javascript","exec":[""]}}],"variable":[{"key":"orion","value":"localhost:1026"},{"key":"datamodels-context.jsonld","value":"https://fiware.github.io/data-models/context.jsonld"},{"key":"scorpio","value":"localhost:9090"}]}Note: If you want to clean up and start over again you can do so with the following command:
\n./services stop\n