diff --git a/FIWARE Relationships using Linked Data.postman_collection.json b/FIWARE Relationships using Linked Data.postman_collection.json index 3705ae9..b5a2ffb 100644 --- a/FIWARE Relationships using Linked Data.postman_collection.json +++ b/FIWARE Relationships using Linked Data.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "9dc4fc1c-5fa8-48cb-a82d-9111faacc238", "name": "NGSI-LD Relationships using Linked Data", - "description": "This tutorial discusses relationships between linked data entities and how the concepts of **JSON-LD** and **NGSI-LD**\ncan be used to interrogate entities and navigate from one entity to another. The tutorial discusses a series of simple\nlinked-data data models based around the supermarket chain’s store finder application, and demonstrates how to design\nmodels holding one-to-one, one-to-many and many-to-many relationships. This **NGSI-LD** tutorial is a direct analogue to\nthe earlier _Understanding Entities and Relationships_ tutorial (which was based on the **NGSI v2** interface). The\ndifferences in relationships created using **NSGI v2** and **NGSI-LD** are highlighted and discussed in detail.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Relationships-Linked-Data/icon/GitHub-Mark-32px.png) [FIWARE 602: Relationships using Linked Data](https://github.com/Fiware/tutorials.Relationships-Linked-Data)\n\n\nAll NGSI data entity attributes can be divided into one of two types.\n\n- _Property_ attributes\n- _Relationship_ attributes\n\nFor each entity, the _Property_ attributes (including various subtypes such as _GeoProperty_ , _TemporalProperty_ and\ntime values) define the current state something in the real world. As the state of the entity changes the `value` of\neach _Property_ is updated to align with the last real world reading of the the attribute. All _Property_ attributes\nrelate to the state of a single entity.\n\n_Relationship_ attributes correspond to the interactions **between** entities (which are expected to change over time).\nThey effectively provide the graph linking the nodes of the data entities together. Each _Relationship_ attribute holds\nan `object` in the form of a URN - effectively a pointer to another object. _Relationship_ attributes do not hold data\nthemselves.\n\nBoth properties and relationships may in turn have a linked embedded structure (of _properties-of-properties_ or\n_properties-of-relationships or relationships-of-properties_ or _relationships-of-relationships_ etc.) which lead a full\ncomplex knowledge graph.\n\n## Designing Data Models using JSON-LD\n\nIn order for computers to be able to navigate linked data structures, proper ontologically correct data models must be\ncreated and a full `@context` must be defined and made accessible. We can do this by reviewing and updating the existing\ndata models from the NGSI v2 [Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\n### Revision: Data Models for a Stock management system as defined using NGSI-v2\n\nAs a reminder, four types of entity were created in the NGSI v2 stock management system. The relationship between the\nfour NGSI v2 entity models was defined as shown below:\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-v2.png)\n\nMore details can be found in the NGSI v2\n[Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\nIn NGSI v2 relationship attributes are just standard properties attributes. By convention NGSI v2 relationship\nattributes are given names starting `ref` and are defined using the `type=\"Relationship\"`. However, this is merely\nconvention and may not be followed in all cases. There is no infallible mechanism for detecting which attributes are\nassociative relationships between entities.\n\n### Data Models for a Stock management system defined using NGSI-LD\n\nThe richer [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) description language is able to define NSGI-LD\nentities by linking entities directly as shown below.\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-ld.png)\n\nThe complete data model must be understandable by both developers and machines.\n\n- A full Human readable definition of this data model can be found\n [online](https://fiware.github.io/tutorials.Step-by-Step/schema).\n- The machine readable JSON-LD defintion can be found at\n [`https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld`](https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld) -\n this file will be used to provide the `@context` to power our NGSI-LD data entities.\n\nFour data models have been created for this NGSI-LD stock management system. The relationships between the models are\ndescribed below:\n\n- The [**Store** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Store/) is now based on and extends the\n FIWARE\n [**Building** model](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html). This\n ensures that it offers standard properties for `name`, `address` and category.\n - A Building will hold `furniture` this is a 1-many relationship.\n - Building :arrow_right: Shelf.\n- The [**Shelf** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Shelf/) is a custom data model defined\n for the tutorial\n - Each **Shelf** is `locatedIn` a **Building**. This is a 1-1 relationship. It is the reciprical relationship to\n `furniture` defined above.\n - Shelf :arrow_right: Building.\n - A **Shelf** is `installedBy` a **Person** - this is a 1-1 relationship. A shelf knows who installed it, but it\n is this knowledge is not part of the Person entity itself.\n - Shelf :arrow_right: Person\n - A **Shelf** `stocks` a given **Product**. This is another 1-1 relationship, and again it is not recipricated. A\n **Product** does not know which **Shelf** it is to be found on.\n - Shelf :arrow_right: Product\n- A [**StockOrder** model](https://fiware.github.io/tutorials.Step-by-Step/schema/StockOrder/) replaces the\n **Inventory Item** bridge table defined for NGSI v2 :\n - A **StockOrder** is `requestedBy` a **Person** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Person.\n - A **StockOrder** is `requestedFor` a **Building** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Building.\n - A **StockOrder** is a request for a specific `orderedProduct` - this 1-1 relationship.\n - StockOrder :arrow_right: Product.\n- The [**Product** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Product/) remains unchanged. It has\n no relationships of its own.\n\nAdditionally some relationships have been defined to be linked to `https://schema.org/Person` entities. This could be\noutlinks to a separate HR system for example.\n\n## Comparison between Linked and Non-Linked Data Systems\n\nObviously within a single isolated Smart System itself, it makes no difference whether a rich, complex linked-data\narchitecture is used or a simpler, non-linked-data system is created. However if the data is designed to be shared, then\nlinked data is a requirement to avoid data silos. An external system is unable to \"know\" what relationships are unless\nthey have been provided in a machine readable form.\n\n### Video: Rich Snippets: Product Search\n\nA simple example of an external system interogating for structured data can be found in online product search. Machines\nfrom third parties such as Google are able to read product information (encoded using a standard\n[**Product** data model](https://jsonld.com/product/)) and display a rich snippet of product information with a standard\nstar rating.\n\n[![](http://img.youtube.com/vi/_-rRxKSm2ic/0.jpg)](https://www.youtube.com/watch?v=_-rRxKSm2ic \"Rich Snippets\")\n\nClick on the image above to watch an introductory video on rich snippets for product search.\n\nFurther machine readable data model examples can be found on the [Steal Our JSON-LD](https://jsonld.com/) website.\n\n## Traversing relationships\n\n> **Example**: Imagine the scenario where a pallet of Products are moved from stock in the warehouse (`stockCount`) onto\n> the shelves of the store (`storeCount`) . How would NGSI v2 and NGSI-LD computations differ?\n\n### Relationships without Linked Data\n\nWithout linked data, there is no machine readable way to connect entities together. Every data relationship must be\nknown in advanced somehow. Within an isolated Smart System this is not an issue, since the architect of the system will\nknow in advance _what-connects-to-what_.\n\nFor example in the simple NGSI v2 Entity Relationships tutorial, a convenience bridge table **InventoryItem** entity had\nbeen created specifically to hold both count on the shelf and count in the warehouse in a single entity. In any\ncomputation only the **InventoryItem** entity would be involved. The `stockCount` value would be decremented and the\n`shelfCount` value would incremented. In the NGSI v2 model both the `storeCount` and the `shelfCount` have been placed\ninto the conceptual **InventoryItem** Entity. This is a necessary workaround for NGSI v2 and it allows for simpler data\nreading and data manipulation. However technically it is ontologically incorrect, as there is no such thing as an\n**InventoryItem** in the real world, it is really two separate ledgers, products bought for the store and products sold\non the shelf, which in turn have an indirect relationship.\n\nSince the entity data is not yet machine readable externally, the programmer is free to design models as she sees fit\nand can decide to update two attributes of one **InventoryItem** Entity or two separate attributes on two separate\n**Shelf** and **StockOrder** entities without regards as to whether these really are real concrete items in the real\nworld. However this means **external systems** cannot discover information for themselves and must be pre-programmed to\nknow where information is held.\n\n### Relationships with Linked Data\n\nWith a well defined data model using linked data, every relationship can be predefined in advance and is discoverable.\nUsing [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) concepts (specifically `@graph` and `@context`) it is\nmuch easier for computers to understand indirect relationships and navigate between linked entities. Due to hese\nadditional annotations it is possible to create usable models which are ontologically correct and therefore **Shelf**\ncan now be directly assigned a `numberOfItems` attribute and bridge table concept is no longer required. This is\nnecessary as other systems may be interogating **Shelf** directly.\n\nSimilarly a real **StockOrder** Entity can be created which holds a entry of which items are currently on order for each\nstore. This is a proper context data entity as `stockCount` describes the current state of a product in the warehouse.\nOnce again this describes a single, real world entity and is ontologically correct.\n\nUnlike the NGSI v2 scenario, with linked data, it would be possible for an **external system** to discover relationships\nand interogate our Supermarket. Imagine for example, an\n[Autonomous Mobile Robot](https://www.intorobotics.com/40-excellent-autonomous-mobile-robots-on-wheels-that-you-can-build-at-home/)\nsystem which is used to move a pallet of products onto a shelf it would be possible for this **external system** to\n\"know\" about our supermarket by navigating the relationships in the linked data the `@graph` from **StockOrder** to\n**Shelf** as shown:\n\n- Some `product:XXX` items have been removed from `stockOrder:0001` - decrement `stockCount`.\n- Interogating the **StockOrder** is discovered that the **Product** is `requestedFor` for a specific URI e.g.\n `store:002`\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:orderedProduct\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The Product ordered for a store\",\n \"rdfs:label\": \"orderedProduct\"\n },\n ...etc\n]\n```\n\n- It is also discovered from the **StockOrder** model that the `requestedFor` URI defines a **Building**\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:requestedFor\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"rdfs:comment\": \"Store for which an item is requested\",\n \"rdfs:label\": \"requestedFor\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Building** model that every **Building** contains `furniture` as an array of URIs.\n- It is discovered from the **Building** model that these URIs represent **Shelf** units\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:furniture\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"rdfs:comment\": \"Units found within a Building\",\n \"rdfs:label\": \"furniture\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Shelf** model that the `stocks` attribute holds a URI representing **Product** items.\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:stocks\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The product found on a shelf\",\n \"rdfs:label\": \"stocks\"\n },\n ...etc\n]\n```\n\n- A request the **Shelf** unit which holds the correct **Product** for the `stocks` attribute is made and the Shelf\n `numberOfItems` attribute can be incremented.\n\nThrough creating and using standard data models and decribing the linked data properly, it would not matter to the robot\nif the underlying system were to change, provided that the Properties and Relationships resolve to fully qualified names\n(FQN) and a complete `@graph`. For example the JSON short name attributes could be amended or the relationships\nredesigned but their real intent (which resolves to a fixed FQN) could still be discovered and used.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml) 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](https://docs.docker.com/compose/install/)\n\n## Cygwin\n\nWe will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n", + "description": "This tutorial discusses relationships between linked data entities and how the concepts of **JSON-LD** and **NGSI-LD**\ncan be used to interrogate entities and navigate from one entity to another. The tutorial discusses a series of simple\nlinked-data data models based around the supermarket chain’s store finder application, and demonstrates how to design\nmodels holding one-to-one, one-to-many and many-to-many relationships. This **NGSI-LD** tutorial is a direct analogue to\nthe earlier _Understanding Entities and Relationships_ tutorial (which was based on the **NGSI v2** interface). The\ndifferences in relationships created using **NSGI v2** and **NGSI-LD** are highlighted and discussed in detail.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Relationships-Linked-Data/icon/GitHub-Mark-32px.png) [FIWARE 602: Relationships using Linked Data](https://github.com/Fiware/tutorials.Relationships-Linked-Data)\n\n\nAll NGSI data entity attributes can be divided into one of two types.\n\n- _Property_ attributes\n- _Relationship_ attributes\n\nFor each entity, the _Property_ attributes (including various subtypes such as _GeoProperty_ , _TemporalProperty_ and\ntime values) define the current state something in the real world. As the state of the entity changes the `value` of\neach _Property_ is updated to align with the last real world reading of the the attribute. All _Property_ attributes\nrelate to the state of a single entity.\n\n_Relationship_ attributes correspond to the interactions **between** entities (which are expected to change over time).\nThey effectively provide the graph linking the nodes of the data entities together. Each _Relationship_ attribute holds\nan `object` in the form of a URN - effectively a pointer to another object. _Relationship_ attributes do not hold data\nthemselves.\n\nBoth properties and relationships may in turn have a linked embedded structure (of _properties-of-properties_ or\n_properties-of-relationships or relationships-of-properties_ or _relationships-of-relationships_ etc.) which lead a full\ncomplex knowledge graph.\n\n## Designing Data Models using JSON-LD\n\nIn order for computers to be able to navigate linked data structures, proper ontologically correct data models must be\ncreated and a full `@context` must be defined and made accessible. We can do this by reviewing and updating the existing\ndata models from the NGSI v2 [Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\n### Revision: Data Models for a Stock management system as defined using NGSI-v2\n\nAs a reminder, four types of entity were created in the NGSI v2 stock management system. The relationship between the\nfour NGSI v2 entity models was defined as shown below:\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-v2.png)\n\nMore details can be found in the NGSI v2\n[Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\nIn NGSI v2 relationship attributes are just standard properties attributes. By convention NGSI v2 relationship\nattributes are given names starting `ref` and are defined using the `type=\"Relationship\"`. However, this is merely\nconvention and may not be followed in all cases. There is no infallible mechanism for detecting which attributes are\nassociative relationships between entities.\n\n### Data Models for a Stock management system defined using NGSI-LD\n\nThe richer [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) description language is able to define NSGI-LD\nentities by linking entities directly as shown below.\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-ld.png)\n\nThe complete data model must be understandable by both developers and machines.\n\n- A full Human readable definition of this data model can be found\n [online](https://fiware.github.io/tutorials.Step-by-Step/schema).\n- The machine readable JSON-LD defintion can be found at\n [`https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld`](https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld) -\n this file will be used to provide the `@context` to power our NGSI-LD data entities.\n\nFour data models have been created for this NGSI-LD stock management system. The relationships between the models are\ndescribed below:\n\n- The [**Store** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Store/) is now based on and extends the\n FIWARE\n [**Building** model](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html). This\n ensures that it offers standard properties for `name`, `address` and category.\n - A Building will hold `furniture` this is a 1-many relationship.\n - Building :arrow_right: Shelf.\n- The [**Shelf** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Shelf/) is a custom data model defined\n for the tutorial\n - Each **Shelf** is `locatedIn` a **Building**. This is a 1-1 relationship. It is the reciprical relationship to\n `furniture` defined above.\n - Shelf :arrow_right: Building.\n - A **Shelf** is `installedBy` a **Person** - this is a 1-1 relationship. A shelf knows who installed it, but it\n is this knowledge is not part of the Person entity itself.\n - Shelf :arrow_right: Person\n - A **Shelf** `stocks` a given **Product**. This is another 1-1 relationship, and again it is not recipricated. A\n **Product** does not know which **Shelf** it is to be found on.\n - Shelf :arrow_right: Product\n- A [**StockOrder** model](https://fiware.github.io/tutorials.Step-by-Step/schema/StockOrder/) replaces the\n **Inventory Item** bridge table defined for NGSI v2 :\n - A **StockOrder** is `requestedBy` a **Person** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Person.\n - A **StockOrder** is `requestedFor` a **Building** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Building.\n - A **StockOrder** is a request for a specific `orderedProduct` - this 1-1 relationship.\n - StockOrder :arrow_right: Product.\n- The [**Product** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Product/) remains unchanged. It has\n no relationships of its own.\n\nAdditionally some relationships have been defined to be linked to `https://schema.org/Person` entities. This could be\noutlinks to a separate HR system for example.\n\n## Comparison between Linked and Non-Linked Data Systems\n\nObviously within a single isolated Smart System itself, it makes no difference whether a rich, complex linked-data\narchitecture is used or a simpler, non-linked-data system is created. However if the data is designed to be shared, then\nlinked data is a requirement to avoid data silos. An external system is unable to \"know\" what relationships are unless\nthey have been provided in a machine readable form.\n\n### Video: Rich Snippets: Product Search\n\nA simple example of an external system interogating for structured data can be found in online product search. Machines\nfrom third parties such as Google are able to read product information (encoded using a standard\n[**Product** data model](https://jsonld.com/product/)) and display a rich snippet of product information with a standard\nstar rating.\n\n[![](http://img.youtube.com/vi/_-rRxKSm2ic/0.jpg)](https://www.youtube.com/watch?v=_-rRxKSm2ic \"Rich Snippets\")\n\nClick on the image above to watch an introductory video on rich snippets for product search.\n\nFurther machine readable data model examples can be found on the [Steal Our JSON-LD](https://jsonld.com/) website.\n\n## Traversing relationships\n\n> **Example**: Imagine the scenario where a pallet of Products are moved from stock in the warehouse (`stockCount`) onto\n> the shelves of the store (`storeCount`) . How would NGSI v2 and NGSI-LD computations differ?\n\n### Relationships without Linked Data\n\nWithout linked data, there is no machine readable way to connect entities together. Every data relationship must be\nknown in advanced somehow. Within an isolated Smart System this is not an issue, since the architect of the system will\nknow in advance _what-connects-to-what_.\n\nFor example in the simple NGSI v2 Entity Relationships tutorial, a convenience bridge table **InventoryItem** entity had\nbeen created specifically to hold both count on the shelf and count in the warehouse in a single entity. In any\ncomputation only the **InventoryItem** entity would be involved. The `stockCount` value would be decremented and the\n`shelfCount` value would incremented. In the NGSI v2 model both the `storeCount` and the `shelfCount` have been placed\ninto the conceptual **InventoryItem** Entity. This is a necessary workaround for NGSI v2 and it allows for simpler data\nreading and data manipulation. However technically it is ontologically incorrect, as there is no such thing as an\n**InventoryItem** in the real world, it is really two separate ledgers, products bought for the store and products sold\non the shelf, which in turn have an indirect relationship.\n\nSince the entity data is not yet machine readable externally, the programmer is free to design models as she sees fit\nand can decide to update two attributes of one **InventoryItem** Entity or two separate attributes on two separate\n**Shelf** and **StockOrder** entities without regards as to whether these really are real concrete items in the real\nworld. However this means **external systems** cannot discover information for themselves and must be pre-programmed to\nknow where information is held.\n\n### Relationships with Linked Data\n\nWith a well defined data model using linked data, every relationship can be predefined in advance and is discoverable.\nUsing [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) concepts (specifically `@graph` and `@context`) it is\nmuch easier for computers to understand indirect relationships and navigate between linked entities. Due to hese\nadditional annotations it is possible to create usable models which are ontologically correct and therefore **Shelf**\ncan now be directly assigned a `numberOfItems` attribute and bridge table concept is no longer required. This is\nnecessary as other systems may be interogating **Shelf** directly.\n\nSimilarly a real **StockOrder** Entity can be created which holds a entry of which items are currently on order for each\nstore. This is a proper context data entity as `stockCount` describes the current state of a product in the warehouse.\nOnce again this describes a single, real world entity and is ontologically correct.\n\nUnlike the NGSI v2 scenario, with linked data, it would be possible for an **external system** to discover relationships\nand interogate our Supermarket. Imagine for example, an\n[Autonomous Mobile Robot](https://www.intorobotics.com/40-excellent-autonomous-mobile-robots-on-wheels-that-you-can-build-at-home/)\nsystem which is used to move a pallet of products onto a shelf it would be possible for this **external system** to\n\"know\" about our supermarket by navigating the relationships in the linked data the `@graph` from **StockOrder** to\n**Shelf** as shown:\n\n- Some `product:XXX` items have been removed from `stockOrder:0001` - decrement `stockCount`.\n- Interogating the **StockOrder** is discovered that the **Product** is `requestedFor` for a specific URI e.g.\n `store:002`\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:orderedProduct\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The Product ordered for a store\",\n \"rdfs:label\": \"orderedProduct\"\n },\n ...etc\n]\n```\n\n- It is also discovered from the **StockOrder** model that the `requestedFor` URI defines a **Building**\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:requestedFor\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"rdfs:comment\": \"Store for which an item is requested\",\n \"rdfs:label\": \"requestedFor\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Building** model that every **Building** contains `furniture` as an array of URIs.\n- It is discovered from the **Building** model that these URIs represent **Shelf** units\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:furniture\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"rdfs:comment\": \"Units found within a Building\",\n \"rdfs:label\": \"furniture\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Shelf** model that the `stocks` attribute holds a URI representing **Product** items.\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:stocks\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The product found on a shelf\",\n \"rdfs:label\": \"stocks\"\n },\n ...etc\n]\n```\n\n- A request the **Shelf** unit which holds the correct **Product** for the `stocks` attribute is made and the Shelf\n `numberOfItems` attribute can be incremented.\n\nThrough creating and using standard data models and decribing the linked data properly, it would not matter to the robot\nif the underlying system were to change, provided that the Properties and Relationships resolve to fully qualified names\n(FQN) and a complete `@graph`. For example the JSON short name attributes could be amended or the relationships\nredesigned but their real intent (which resolves to a fixed FQN) could still be discovered and used.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml) 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](https://docs.docker.com/compose/install/)\n\n## WSL\n\nWe will start up our services using a simple bash script. Windows users should download the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "513743", "_collection_link": "https://fiware.postman.co/workspace/NGSI-v2-Tutorials~56ef8b2e-ab05-408c-bbe9-7714cfe08cf6/collection/513743-9dc4fc1c-5fa8-48cb-a82d-9111faacc238?action=share&source=collection_link&creator=513743" diff --git a/NGSI-LD Relationships using Linked Data.postman_collection.json b/NGSI-LD Relationships using Linked Data.postman_collection.json index 22102d3..f38a48e 100644 --- a/NGSI-LD Relationships using Linked Data.postman_collection.json +++ b/NGSI-LD Relationships using Linked Data.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "9dc4fc1c-5fa8-48cb-a82d-9111faacc238", "name": "NGSI-LD Relationships using Linked Data", - "description": "This tutorial discusses relationships between linked data entities and how the concepts of **JSON-LD** and **NGSI-LD**\ncan be used to interrogate entities and navigate from one entity to another. The tutorial discusses a series of simple\nlinked-data data models based around the supermarket chain’s store finder application, and demonstrates how to design\nmodels holding one-to-one, one-to-many and many-to-many relationships. This **NGSI-LD** tutorial is a direct analogue to\nthe earlier _Understanding Entities and Relationships_ tutorial (which was based on the **NGSI v2** interface). The\ndifferences in relationships created using **NSGI v2** and **NGSI-LD** are highlighted and discussed in detail.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Relationships-Linked-Data/icon/GitHub-Mark-32px.png) [FIWARE 602: Relationships using Linked Data](https://github.com/Fiware/tutorials.Relationships-Linked-Data)\n\n\nAll NGSI data entity attributes can be divided into one of two types.\n\n- _Property_ attributes\n- _Relationship_ attributes\n\nFor each entity, the _Property_ attributes (including various subtypes such as _GeoProperty_ , _TemporalProperty_ and\ntime values) define the current state something in the real world. As the state of the entity changes the `value` of\neach _Property_ is updated to align with the last real world reading of the the attribute. All _Property_ attributes\nrelate to the state of a single entity.\n\n_Relationship_ attributes correspond to the interactions **between** entities (which are expected to change over time).\nThey effectively provide the graph linking the nodes of the data entities together. Each _Relationship_ attribute holds\nan `object` in the form of a URN - effectively a pointer to another object. _Relationship_ attributes do not hold data\nthemselves.\n\nBoth properties and relationships may in turn have a linked embedded structure (of _properties-of-properties_ or\n_properties-of-relationships or relationships-of-properties_ or _relationships-of-relationships_ etc.) which lead a full\ncomplex knowledge graph.\n\n## Designing Data Models using JSON-LD\n\nIn order for computers to be able to navigate linked data structures, proper ontologically correct data models must be\ncreated and a full `@context` must be defined and made accessible. We can do this by reviewing and updating the existing\ndata models from the NGSI v2 [Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\n### Revision: Data Models for a Stock management system as defined using NGSI-v2\n\nAs a reminder, four types of entity were created in the NGSI v2 stock management system. The relationship between the\nfour NGSI v2 entity models was defined as shown below:\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-v2.png)\n\nMore details can be found in the NGSI v2\n[Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\nIn NGSI v2 relationship attributes are just standard properties attributes. By convention NGSI v2 relationship\nattributes are given names starting `ref` and are defined using the `type=\"Relationship\"`. However, this is merely\nconvention and may not be followed in all cases. There is no infallible mechanism for detecting which attributes are\nassociative relationships between entities.\n\n### Data Models for a Stock management system defined using NGSI-LD\n\nThe richer [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) description language is able to define NSGI-LD\nentities by linking entities directly as shown below.\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-ld.png)\n\nThe complete data model must be understandable by both developers and machines.\n\n- A full Human readable definition of this data model can be found\n [online](https://fiware.github.io/tutorials.Step-by-Step/schema).\n- The machine readable JSON-LD defintion can be found at\n [`https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld`](https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld) -\n this file will be used to provide the `@context` to power our NGSI-LD data entities.\n\nFour data models have been created for this NGSI-LD stock management system. The relationships between the models are\ndescribed below:\n\n- The [**Store** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Store/) is now based on and extends the\n FIWARE\n [**Building** model](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html). This\n ensures that it offers standard properties for `name`, `address` and category.\n - A Building will hold `furniture` this is a 1-many relationship.\n - Building :arrow_right: Shelf.\n- The [**Shelf** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Shelf/) is a custom data model defined\n for the tutorial\n - Each **Shelf** is `locatedIn` a **Building**. This is a 1-1 relationship. It is the reciprical relationship to\n `furniture` defined above.\n - Shelf :arrow_right: Building.\n - A **Shelf** is `installedBy` a **Person** - this is a 1-1 relationship. A shelf knows who installed it, but it\n is this knowledge is not part of the Person entity itself.\n - Shelf :arrow_right: Person\n - A **Shelf** `stocks` a given **Product**. This is another 1-1 relationship, and again it is not recipricated. A\n **Product** does not know which **Shelf** it is to be found on.\n - Shelf :arrow_right: Product\n- A [**StockOrder** model](https://fiware.github.io/tutorials.Step-by-Step/schema/StockOrder/) replaces the\n **Inventory Item** bridge table defined for NGSI v2 :\n - A **StockOrder** is `requestedBy` a **Person** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Person.\n - A **StockOrder** is `requestedFor` a **Building** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Building.\n - A **StockOrder** is a request for a specific `orderedProduct` - this 1-1 relationship.\n - StockOrder :arrow_right: Product.\n- The [**Product** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Product/) remains unchanged. It has\n no relationships of its own.\n\nAdditionally some relationships have been defined to be linked to `https://schema.org/Person` entities. This could be\noutlinks to a separate HR system for example.\n\n## Comparison between Linked and Non-Linked Data Systems\n\nObviously within a single isolated Smart System itself, it makes no difference whether a rich, complex linked-data\narchitecture is used or a simpler, non-linked-data system is created. However if the data is designed to be shared, then\nlinked data is a requirement to avoid data silos. An external system is unable to \"know\" what relationships are unless\nthey have been provided in a machine readable form.\n\n### Video: Rich Snippets: Product Search\n\nA simple example of an external system interogating for structured data can be found in online product search. Machines\nfrom third parties such as Google are able to read product information (encoded using a standard\n[**Product** data model](https://jsonld.com/product/)) and display a rich snippet of product information with a standard\nstar rating.\n\n[![](http://img.youtube.com/vi/_-rRxKSm2ic/0.jpg)](https://www.youtube.com/watch?v=_-rRxKSm2ic \"Rich Snippets\")\n\nClick on the image above to watch an introductory video on rich snippets for product search.\n\nFurther machine readable data model examples can be found on the [Steal Our JSON-LD](https://jsonld.com/) website.\n\n## Traversing relationships\n\n> **Example**: Imagine the scenario where a pallet of Products are moved from stock in the warehouse (`stockCount`) onto\n> the shelves of the store (`storeCount`) . How would NGSI v2 and NGSI-LD computations differ?\n\n### Relationships without Linked Data\n\nWithout linked data, there is no machine readable way to connect entities together. Every data relationship must be\nknown in advanced somehow. Within an isolated Smart System this is not an issue, since the architect of the system will\nknow in advance _what-connects-to-what_.\n\nFor example in the simple NGSI v2 Entity Relationships tutorial, a convenience bridge table **InventoryItem** entity had\nbeen created specifically to hold both count on the shelf and count in the warehouse in a single entity. In any\ncomputation only the **InventoryItem** entity would be involved. The `stockCount` value would be decremented and the\n`shelfCount` value would incremented. In the NGSI v2 model both the `storeCount` and the `shelfCount` have been placed\ninto the conceptual **InventoryItem** Entity. This is a necessary workaround for NGSI v2 and it allows for simpler data\nreading and data manipulation. However technically it is ontologically incorrect, as there is no such thing as an\n**InventoryItem** in the real world, it is really two separate ledgers, products bought for the store and products sold\non the shelf, which in turn have an indirect relationship.\n\nSince the entity data is not yet machine readable externally, the programmer is free to design models as she sees fit\nand can decide to update two attributes of one **InventoryItem** Entity or two separate attributes on two separate\n**Shelf** and **StockOrder** entities without regards as to whether these really are real concrete items in the real\nworld. However this means **external systems** cannot discover information for themselves and must be pre-programmed to\nknow where information is held.\n\n### Relationships with Linked Data\n\nWith a well defined data model using linked data, every relationship can be predefined in advance and is discoverable.\nUsing [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) concepts (specifically `@graph` and `@context`) it is\nmuch easier for computers to understand indirect relationships and navigate between linked entities. Due to hese\nadditional annotations it is possible to create usable models which are ontologically correct and therefore **Shelf**\ncan now be directly assigned a `numberOfItems` attribute and bridge table concept is no longer required. This is\nnecessary as other systems may be interogating **Shelf** directly.\n\nSimilarly a real **StockOrder** Entity can be created which holds a entry of which items are currently on order for each\nstore. This is a proper context data entity as `stockCount` describes the current state of a product in the warehouse.\nOnce again this describes a single, real world entity and is ontologically correct.\n\nUnlike the NGSI v2 scenario, with linked data, it would be possible for an **external system** to discover relationships\nand interogate our Supermarket. Imagine for example, an\n[Autonomous Mobile Robot](https://www.intorobotics.com/40-excellent-autonomous-mobile-robots-on-wheels-that-you-can-build-at-home/)\nsystem which is used to move a pallet of products onto a shelf it would be possible for this **external system** to\n\"know\" about our supermarket by navigating the relationships in the linked data the `@graph` from **StockOrder** to\n**Shelf** as shown:\n\n- Some `product:XXX` items have been removed from `stockOrder:0001` - decrement `stockCount`.\n- Interogating the **StockOrder** is discovered that the **Product** is `requestedFor` for a specific URI e.g.\n `store:002`\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:orderedProduct\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The Product ordered for a store\",\n \"rdfs:label\": \"orderedProduct\"\n },\n ...etc\n]\n```\n\n- It is also discovered from the **StockOrder** model that the `requestedFor` URI defines a **Building**\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:requestedFor\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"rdfs:comment\": \"Store for which an item is requested\",\n \"rdfs:label\": \"requestedFor\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Building** model that every **Building** contains `furniture` as an array of URIs.\n- It is discovered from the **Building** model that these URIs represent **Shelf** units\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:furniture\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"rdfs:comment\": \"Units found within a Building\",\n \"rdfs:label\": \"furniture\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Shelf** model that the `stocks` attribute holds a URI representing **Product** items.\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:stocks\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The product found on a shelf\",\n \"rdfs:label\": \"stocks\"\n },\n ...etc\n]\n```\n\n- A request the **Shelf** unit which holds the correct **Product** for the `stocks` attribute is made and the Shelf\n `numberOfItems` attribute can be incremented.\n\nThrough creating and using standard data models and decribing the linked data properly, it would not matter to the robot\nif the underlying system were to change, provided that the Properties and Relationships resolve to fully qualified names\n(FQN) and a complete `@graph`. For example the JSON short name attributes could be amended or the relationships\nredesigned but their real intent (which resolves to a fixed FQN) could still be discovered and used.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml) 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](https://docs.docker.com/compose/install/)\n\n## Cygwin\n\nWe will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n", + "description": "This tutorial discusses relationships between linked data entities and how the concepts of **JSON-LD** and **NGSI-LD**\ncan be used to interrogate entities and navigate from one entity to another. The tutorial discusses a series of simple\nlinked-data data models based around the supermarket chain’s store finder application, and demonstrates how to design\nmodels holding one-to-one, one-to-many and many-to-many relationships. This **NGSI-LD** tutorial is a direct analogue to\nthe earlier _Understanding Entities and Relationships_ tutorial (which was based on the **NGSI v2** interface). The\ndifferences in relationships created using **NSGI v2** and **NGSI-LD** are highlighted and discussed in detail.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Relationships-Linked-Data/icon/GitHub-Mark-32px.png) [FIWARE 602: Relationships using Linked Data](https://github.com/Fiware/tutorials.Relationships-Linked-Data)\n\n\nAll NGSI data entity attributes can be divided into one of two types.\n\n- _Property_ attributes\n- _Relationship_ attributes\n\nFor each entity, the _Property_ attributes (including various subtypes such as _GeoProperty_ , _TemporalProperty_ and\ntime values) define the current state something in the real world. As the state of the entity changes the `value` of\neach _Property_ is updated to align with the last real world reading of the the attribute. All _Property_ attributes\nrelate to the state of a single entity.\n\n_Relationship_ attributes correspond to the interactions **between** entities (which are expected to change over time).\nThey effectively provide the graph linking the nodes of the data entities together. Each _Relationship_ attribute holds\nan `object` in the form of a URN - effectively a pointer to another object. _Relationship_ attributes do not hold data\nthemselves.\n\nBoth properties and relationships may in turn have a linked embedded structure (of _properties-of-properties_ or\n_properties-of-relationships or relationships-of-properties_ or _relationships-of-relationships_ etc.) which lead a full\ncomplex knowledge graph.\n\n## Designing Data Models using JSON-LD\n\nIn order for computers to be able to navigate linked data structures, proper ontologically correct data models must be\ncreated and a full `@context` must be defined and made accessible. We can do this by reviewing and updating the existing\ndata models from the NGSI v2 [Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\n### Revision: Data Models for a Stock management system as defined using NGSI-v2\n\nAs a reminder, four types of entity were created in the NGSI v2 stock management system. The relationship between the\nfour NGSI v2 entity models was defined as shown below:\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-v2.png)\n\nMore details can be found in the NGSI v2\n[Entity Relationships](https://github.com/FIWARE/tutorials.Entity-Relationships) tutorial.\n\nIn NGSI v2 relationship attributes are just standard properties attributes. By convention NGSI v2 relationship\nattributes are given names starting `ref` and are defined using the `type=\"Relationship\"`. However, this is merely\nconvention and may not be followed in all cases. There is no infallible mechanism for detecting which attributes are\nassociative relationships between entities.\n\n### Data Models for a Stock management system defined using NGSI-LD\n\nThe richer [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) description language is able to define NSGI-LD\nentities by linking entities directly as shown below.\n\n![](https://fiware.github.io/tutorials.Relationships-Linked-Data/img/entities-ld.png)\n\nThe complete data model must be understandable by both developers and machines.\n\n- A full Human readable definition of this data model can be found\n [online](https://fiware.github.io/tutorials.Step-by-Step/schema).\n- The machine readable JSON-LD defintion can be found at\n [`https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld`](https://fiware.github.io/tutorials.Step-by-Step/tutorials-context.jsonld) -\n this file will be used to provide the `@context` to power our NGSI-LD data entities.\n\nFour data models have been created for this NGSI-LD stock management system. The relationships between the models are\ndescribed below:\n\n- The [**Store** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Store/) is now based on and extends the\n FIWARE\n [**Building** model](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html). This\n ensures that it offers standard properties for `name`, `address` and category.\n - A Building will hold `furniture` this is a 1-many relationship.\n - Building :arrow_right: Shelf.\n- The [**Shelf** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Shelf/) is a custom data model defined\n for the tutorial\n - Each **Shelf** is `locatedIn` a **Building**. This is a 1-1 relationship. It is the reciprical relationship to\n `furniture` defined above.\n - Shelf :arrow_right: Building.\n - A **Shelf** is `installedBy` a **Person** - this is a 1-1 relationship. A shelf knows who installed it, but it\n is this knowledge is not part of the Person entity itself.\n - Shelf :arrow_right: Person\n - A **Shelf** `stocks` a given **Product**. This is another 1-1 relationship, and again it is not recipricated. A\n **Product** does not know which **Shelf** it is to be found on.\n - Shelf :arrow_right: Product\n- A [**StockOrder** model](https://fiware.github.io/tutorials.Step-by-Step/schema/StockOrder/) replaces the\n **Inventory Item** bridge table defined for NGSI v2 :\n - A **StockOrder** is `requestedBy` a **Person** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Person.\n - A **StockOrder** is `requestedFor` a **Building** - this is a 1-1 relationship.\n - StockOrder :arrow_right: Building.\n - A **StockOrder** is a request for a specific `orderedProduct` - this 1-1 relationship.\n - StockOrder :arrow_right: Product.\n- The [**Product** model](https://fiware.github.io/tutorials.Step-by-Step/schema/Product/) remains unchanged. It has\n no relationships of its own.\n\nAdditionally some relationships have been defined to be linked to `https://schema.org/Person` entities. This could be\noutlinks to a separate HR system for example.\n\n## Comparison between Linked and Non-Linked Data Systems\n\nObviously within a single isolated Smart System itself, it makes no difference whether a rich, complex linked-data\narchitecture is used or a simpler, non-linked-data system is created. However if the data is designed to be shared, then\nlinked data is a requirement to avoid data silos. An external system is unable to \"know\" what relationships are unless\nthey have been provided in a machine readable form.\n\n### Video: Rich Snippets: Product Search\n\nA simple example of an external system interogating for structured data can be found in online product search. Machines\nfrom third parties such as Google are able to read product information (encoded using a standard\n[**Product** data model](https://jsonld.com/product/)) and display a rich snippet of product information with a standard\nstar rating.\n\n[![](http://img.youtube.com/vi/_-rRxKSm2ic/0.jpg)](https://www.youtube.com/watch?v=_-rRxKSm2ic \"Rich Snippets\")\n\nClick on the image above to watch an introductory video on rich snippets for product search.\n\nFurther machine readable data model examples can be found on the [Steal Our JSON-LD](https://jsonld.com/) website.\n\n## Traversing relationships\n\n> **Example**: Imagine the scenario where a pallet of Products are moved from stock in the warehouse (`stockCount`) onto\n> the shelves of the store (`storeCount`) . How would NGSI v2 and NGSI-LD computations differ?\n\n### Relationships without Linked Data\n\nWithout linked data, there is no machine readable way to connect entities together. Every data relationship must be\nknown in advanced somehow. Within an isolated Smart System this is not an issue, since the architect of the system will\nknow in advance _what-connects-to-what_.\n\nFor example in the simple NGSI v2 Entity Relationships tutorial, a convenience bridge table **InventoryItem** entity had\nbeen created specifically to hold both count on the shelf and count in the warehouse in a single entity. In any\ncomputation only the **InventoryItem** entity would be involved. The `stockCount` value would be decremented and the\n`shelfCount` value would incremented. In the NGSI v2 model both the `storeCount` and the `shelfCount` have been placed\ninto the conceptual **InventoryItem** Entity. This is a necessary workaround for NGSI v2 and it allows for simpler data\nreading and data manipulation. However technically it is ontologically incorrect, as there is no such thing as an\n**InventoryItem** in the real world, it is really two separate ledgers, products bought for the store and products sold\non the shelf, which in turn have an indirect relationship.\n\nSince the entity data is not yet machine readable externally, the programmer is free to design models as she sees fit\nand can decide to update two attributes of one **InventoryItem** Entity or two separate attributes on two separate\n**Shelf** and **StockOrder** entities without regards as to whether these really are real concrete items in the real\nworld. However this means **external systems** cannot discover information for themselves and must be pre-programmed to\nknow where information is held.\n\n### Relationships with Linked Data\n\nWith a well defined data model using linked data, every relationship can be predefined in advance and is discoverable.\nUsing [JSON-LD](https://json-ld.org/spec/FCGS/json-ld/20130328) concepts (specifically `@graph` and `@context`) it is\nmuch easier for computers to understand indirect relationships and navigate between linked entities. Due to hese\nadditional annotations it is possible to create usable models which are ontologically correct and therefore **Shelf**\ncan now be directly assigned a `numberOfItems` attribute and bridge table concept is no longer required. This is\nnecessary as other systems may be interogating **Shelf** directly.\n\nSimilarly a real **StockOrder** Entity can be created which holds a entry of which items are currently on order for each\nstore. This is a proper context data entity as `stockCount` describes the current state of a product in the warehouse.\nOnce again this describes a single, real world entity and is ontologically correct.\n\nUnlike the NGSI v2 scenario, with linked data, it would be possible for an **external system** to discover relationships\nand interogate our Supermarket. Imagine for example, an\n[Autonomous Mobile Robot](https://www.intorobotics.com/40-excellent-autonomous-mobile-robots-on-wheels-that-you-can-build-at-home/)\nsystem which is used to move a pallet of products onto a shelf it would be possible for this **external system** to\n\"know\" about our supermarket by navigating the relationships in the linked data the `@graph` from **StockOrder** to\n**Shelf** as shown:\n\n- Some `product:XXX` items have been removed from `stockOrder:0001` - decrement `stockCount`.\n- Interogating the **StockOrder** is discovered that the **Product** is `requestedFor` for a specific URI e.g.\n `store:002`\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:orderedProduct\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The Product ordered for a store\",\n \"rdfs:label\": \"orderedProduct\"\n },\n ...etc\n]\n```\n\n- It is also discovered from the **StockOrder** model that the `requestedFor` URI defines a **Building**\n\n```json\n \"@graph\": [\n {\n \"@id\": \"tutorial:requestedFor\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:StockOrder\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"rdfs:comment\": \"Store for which an item is requested\",\n \"rdfs:label\": \"requestedFor\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Building** model that every **Building** contains `furniture` as an array of URIs.\n- It is discovered from the **Building** model that these URIs represent **Shelf** units\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:furniture\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"fiware:Building\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"rdfs:comment\": \"Units found within a Building\",\n \"rdfs:label\": \"furniture\"\n },\n ...etc\n]\n```\n\n- It is discovered from the **Shelf** model that the `stocks` attribute holds a URI representing **Product** items.\n\n```json\n\"@graph\": [\n {\n \"@id\": \"tutorial:stocks\",\n \"@type\": \"https://uri.etsi.org/ngsi-ld/Relationship\",\n \"schema:domainIncludes\": [{\"@id\": \"tutorial:Shelf\"}],\n \"schema:rangeIncludes\": [{\"@id\": \"tutorial:Product\"}],\n \"rdfs:comment\": \"The product found on a shelf\",\n \"rdfs:label\": \"stocks\"\n },\n ...etc\n]\n```\n\n- A request the **Shelf** unit which holds the correct **Product** for the `stocks` attribute is made and the Shelf\n `numberOfItems` attribute can be incremented.\n\nThrough creating and using standard data models and decribing the linked data properly, it would not matter to the robot\nif the underlying system were to change, provided that the Properties and Relationships resolve to fully qualified names\n(FQN) and a complete `@graph`. For example the JSON short name attributes could be amended or the relationships\nredesigned but their real intent (which resolves to a fixed FQN) could still be discovered and used.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple all components will be run using [Docker](https://www.docker.com). **Docker** is a container\ntechnology which allows to different components isolated into their respective environments.\n\n- To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker applications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Identity-Management/master/docker-compose.yml) 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](https://docs.docker.com/compose/install/)\n\n## WSL\n\nWe will start up our services using a simple bash script. Windows users should download the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install)\nto provide a command-line functionality similar to a Linux distribution on Windows.\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "_exporter_id": "513743", "_collection_link": "https://fiware.postman.co/workspace/NGSI-v2-Tutorials~56ef8b2e-ab05-408c-bbe9-7714cfe08cf6/collection/513743-9dc4fc1c-5fa8-48cb-a82d-9111faacc238?action=share&source=collection_link&creator=513743" diff --git a/README.ja.md b/README.ja.md index cdf3ad4..85a7958 100644 --- a/README.ja.md +++ b/README.ja.md @@ -40,7 +40,7 @@ - [リンクト・データとのリレーションシップ](#relationships-with-linked-data) - [前提条件](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [アーキテクチャ](#architecture) - [起動](#start-up) - [データ・エンティティの作成と関連付け](#creating-and-associating-data-entities) @@ -339,12 +339,10 @@ JSON の短縮名属性 (short name attributes) を修正したり、リレー できることを意味します。Docker Compose は、Docker for Windows および Docker for Mac の一部としてデフォルトでインストール されますが、Linux ユーザは[こちら](https://docs.docker.com/compose/install/)にある手順に従う必要があります。 - - -## Cygwin +## WSL 簡単な bash スクリプトを使ってサービスを開始します。Windows ユーザは、Windows 上の Linux ディストリビューションに -似たコマンドライン機能を提供するために [cygwin](http://www.cygwin.com/) をダウンロードするべきです。 +似たコマンドライン機能を提供するために [を使用して Windows に Linux をインストールする方法](https://learn.microsoft.com/ja-jp/windows/wsl/install) をダウンロードするべきです。 diff --git a/README.md b/README.md index bbdc4f9..4410254 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ The tutorial uses [cUrl](https://ec.haxx.se/) commands throughout, but is also a - [Relationships with Linked Data](#relationships-with-linked-data) - [Prerequisites](#prerequisites) - [Docker](#docker) - - [Cygwin](#cygwin) + - [WSL](#wsl) - [Architecture](#architecture) - [Start Up](#start-up) - [Creating and Associating Data Entities](#creating-and-associating-data-entities) @@ -325,10 +325,11 @@ is used configure the required services for the application. This means all cont single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users will need to follow the instructions found [here](https://docs.docker.com/compose/install/) -## Cygwin +## WSL -We will start up our services using a simple bash script. Windows users should download [cygwin](http://www.cygwin.com/) -to provide a command-line functionality similar to a Linux distribution on Windows. +We will start up our services using a simple bash script. Windows users should download the +[Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a command-line +functionality similar to a Linux distribution on Windows. # Architecture