Selective Sharing for Metadata and Data

On this page, we will cover:

• An introduction to Selective Sharing
• Selective Metadata Sharing
• Selective Data Sharing
• How to configure the AllowList properties
• Designing for granular visibility and access control

An introduction to Selective Sharing

A Digital Twin is also composed of Metadata and Data.
Metadata is a description of a Digital Twin, which may include 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.

📘

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:

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.

📘

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:

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 preventing any data sharing with parties in the 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.

2. 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.

3. 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.