Selective Sharing for Metadata and Data

On this page, we will cover:

An introduction to Selective Sharing

A Digital Twin is composed of Metadata and Data.
Metadata is a description of a Digital Twin, which includes its location along with a list of properties, which are semantically described.
Data is the streaming information, to be shared with or received by a Digital Twin.

As the owner of an IOTICSpace, you're in control of all your Twins, therefore you own all the Metadata and Data stored in and streaming through the Twins. IOTICS allows your Twins to selectively share their Metadata and Data with Twins which belong to other IOTICSpaces, also known as Hosts. The values for Selective Sharing are ALL HOSTS, NO HOST and HOST IDs (for a set of selected Host IDs).

🚧

We use the terms IOTICSpace and Host interchangeably throughout this document.

Selective Metadata Sharing

  • Whether the Digital Twin's Metadata is visible or not to other Hosts. The Twins’ Metadata will always be visible in the same Host.
  • It can be enabled selectively on a twin-by-twin basis.
  • The Twin's visibility is set by updating the Digital Twin's hostMetadataAllowList property.

Values

As a Twin Property, the hostMetadataAllowList value is defined by a Key-Value pair.
While its Key is defined by the following URI: http://data.iotics.com/public#hostMetadataAllowList, its Value changes according to the desired behaviour as specified in the table below.

ValueDefinition
http://data.iotics.com/public#allAllows all Twins from all Hosts to find and describe your Digital Twin
http://data.iotics.com/public#noneKeeps your Digital Twin hidden from other Hosts
did:iotics:didexample1234abcdDigital Twins will be visible only from the selected Hosts

📘

Default values for Metadata sharing

Host Twin - All Hosts
Other Twins - No Host

Check out all possible combinations on this table with regards to the hostMetadataAllowList:

DIGITAL TWINVisibility from your own HostVisibility from another Host
NO HOST🟢The Digital Twin can be found (Metadata visible)🔴The Digital Twin cannot be found (Metadata not visible)
HOST IDs🟢The Digital Twin can be found (Metadata visible)🟡The Digital Twin can ONLY be found by the specified Host IDs added to the Digital Twin's AllowList
ALL HOSTS🟢The Digital Twin can be found (Metadata visible)🟢The Digital Twin can be found (Metadata visible)

Selective Data Sharing

  • Whether a Digital Twin's Data is accessible or not by a Digital Twin from other Hosts. The Twins’ Data will always be accessible to other Twins in the same Host.
  • It can be enabled selectively on a twin-by-twin basis.
  • The Twin's accessibility is set by updating the Digital Twin's hostAllowList property.
  • The Host's accessibility is set by updating the Host Twin's hostAllowList property.

Values

As a Twin Property, the hostAllowList value is defined by a Key-Value pair.
While its Key is defined by the following URI: http://data.iotics.com/public#hostAllowList, its Value changes according to the desired behaviour as specified in the table below.

ValueDefinition
http://data.iotics.com/public#allAllows Twins from all Hosts to share and receive data from your Digital Twin
http://data.iotics.com/public#hostAllowListBlocks your Digital Twin from exchanging data with Twins from other Hosts
did:iotics:didexample1234abcdDigital Twins will be accessible only from the selected Hosts

📘

Default values for Data sharing

Host Twin - All Hosts
Other Twins - No Host

The value specified in the Host Twin Data AllowList directly affects ANY Twin's accessibility and visibility - meaning it is the gatekeeper to allow your Twin to be visible and to interact with any other Twin. Check out all possible combinations on this table with regards to the hostAllowList:

HOST TWINDIGITAL TWINAccessibility from your own HostAccessibility from another Host
NO HOSTNO HOST🟢The Digital Twin's Data can be accessed🔴The Digital Twins' Data is not accessible and Metadata is not visible
HOST IDs🟢The Digital Twin's Data can be accessed🔴The Digital Twins' Data is not accessible and Metadata is not visible
ALL HOSTS🟢The Digital Twin's Data can be accessed🔴The Digital Twins' Data is not accessible and Metadata is not visible
HOST IDsNO HOST🟢The Digital Twin's Data can be accessed🔴The Digital Twins' Data is not accessible and Metadata is visible ONLY by the specified Host IDs added to the Host Twin's
HOST IDs🟢The Digital Twin's Data can be accessed🟡The Digital Twins' Data can ONLY be accessed and Metadata be visible by the specified Host IDs added to the Host Twin's and to the Digital Twin’s AllowList
ALL HOSTS🟢The Digital Twin's Data can be accessed🟡The Digital Twins' Data can ONLY be accessed and Metadata be visible by the specified Host IDs added to the Host Twin's and to the Digital Twin’s AllowList
ALL HOSTSNO HOST🟢The Digital Twin's Data can be accessed🔴The Digital Twins' Data is not accessible
HOST IDs🟢The Digital Twin's Data can be accessed🟡The Digital Twins' Data can ONLY be accessed by the specified Host IDs added to the Digital Twin’s AllowList
ALL HOSTS🟢The Digital Twin's Data can be accessed🟢The Digital Twin's Data can be accessed

How to configure the AllowList properties

Updating the Host Twin or an individual Digital Twin follows the same principle, meaning that the AllowList has to be updated to either ALL HOSTS, NO HOST or HOST ID.

To change the properties in the Twin’s AllowList, use the Update operation, which allows the deletion of the AllowList properties and the re-addition of the same properties with new values.

Designing for granular visibility and access control

Combining visibility and access permissions for the entire Host with individual Twins results in granular access control. When configuring how your Twin will share Metadata and Data, consider the following best practices.

  1. What are the least restrictive settings? Consider that:
  • Restricting the Host Twin to NO HOST may be tempting initially, however it will leave you with a Host unable to be found or to exchange data with anyone (therefore unable to join any data ecosystem). We recommend the Host Twin is set to ALL HOSTS or to a set of specific HOST IDs, for future extensibility.
  • Updating the AllowList of individual Digital Twins can be done by any authorised agent, the Host Twin can only be updated by admins.
  1. Do you need to share all or only parts of a Digital Twin? If you only need to share some of your Digital Twin's Data with a third party, consider that:
  • In IOTICS one can decide whether to share only the Metadata, only the Data, or the entire Digital Twin (Metadata + Data). If you still want parts of the Metadata or parts of the Data to be accessed, you can copy your existing Twin, remove any details you don't want to share, and share that new twin instead.
  • This will also allow you to keep on top of your selective sharing configuration, may you need to manage more than 2 third parties with different data access needs (search by Host Twin DID will be handy).
  • Keep in mind that in order to exchange its Metadata and Data, a Twin has to be visible and accessible (respectively) to the Host interested in it. When you set your Twin's Data AllowList to a specific HOST ID, make sure their Metadata AllowList is also updated to the same HOST ID.
  1. Is there any potential conflict between your Host Twin and Digital Twin settings? Consider:
  • Regularly review your settings, if the permissions contradict themselves, the most restrictive and secure permissions are applied. Please see the table above for more information.
  • If you need help designing your visibility or accessibility settings, please get in touch with us.

In the next section, you'll find a tutorial on how to update the Host Twin AllowList.