Attribute introduction

This guide provides an introduction to Attributes in the enmeshed context. Attributes are used to store information about Identities or data that is relevant in a Relationship between Identities. There are therefore two types of Attributes, the IdentityAttributes and the RelationshipAttributes, which are designed for these different purposes. Both have in common that they have a value property that contains the actual value of the Attribute, whereby it is possible to select from a long list of possible Attribute value types. They define the format, the validation rules and the information display for the stored data. Furthermore, an Attribute is technically stored as the content of a LocalAttribute, in whose other properties metadata can be found.

IdentityAttributes

IdentityAttributes play a pivotal role in the management and exchange of information within the networked ecosystem. An IdentityAttribute stores specific information about an Identity, which can be a person or an organization. The semantic meaning of an IdentityAttribute is determined by its IdentityAttribute value type.

IdentityAttribute value types

The IdentityAttribute value types are used to define the type of the value property of an IdentityAttribute. In order to fulfill various purposes, many such IdentityAttribute value types are provided. If the IdentityAttribute value type used is not sufficient to clearly characterize the IdentityAttribute, tags can be used for a more precise description of its meaning. Apart from custom tags, which must have the prefix x: or X:, Backbone-defined tags may be used, which can be queried using the Get AttributeTagCollection use case and which must start with the prefix bkb:. Moreover, the prefixes urn:, language: and mimetype: are supported, and language: must be followed by a valid ISO 639 language code and mimetype: by a valid MIME type matching the pattern ^[a-z-*]+/[a-z-*]+$.

The storage of multiple IdentityAttributes of the same value type is possible. If an Identity receives a Request for an IdentityAttribute of a certain value type, it can choose which of the matching IdentityAttributes it wants to provide for its Response to the Request. For example, storing multiple IdentityAttributes of the same value type is beneficial if an Identity has more than one residential address. Using tags helps to distinguish such IdentityAttributes from each other.

Depending on what IdentityAttribute value type is used, the associated IdentityAttribute is either a simple IdentityAttribute or a complex IdentityAttribute.

Simple IdentityAttributes

A simple IdentityAttribute is an IdentityAttribute with an IdentityAttribute value type which only has a single property with the name value. This property stores the actual value of the IdentityAttribute. Examples of simple IdentityAttributes are IdentityAttributes with IdentityAttribute value type DisplayName or EMailAddress.

Complex IdentityAttributes

A complex IdentityAttribute is an IdentityAttribute with an IdentityAttribute value type which has multiple properties instead of only one value property. Examples of complex IdentityAttributes are IdentityAttributes with IdentityAttribute value type BirthDate or StreetAddress.

LocalAttributes and IdentityAttributes

From a technical perspective, an IdentityAttribute is always stored as the content of a LocalAttribute. A LocalAttribute whose content is given by an IdentityAttribute can be an OwnIdentityAttribute or a PeerIdentityAttribute.

OwnIdentityAttributes

When an Identity creates an IdentityAttribute for itself, an OwnIdentityAttribute is created. Its content is given by the IdentityAttribute owned by the Identity.

An Identity may share the underlying IdentityAttribute of an OwnIdentityAttribute with a peer. This can be done by using a suitable Request.

PeerIdentityAttributes

When an IdentityAttribute is shared by its owner, AttributeForwardingDetails associated with the OwnIdentityAttribute are created in the wallet of the owner. They make it possible to record with whom an IdentityAttribute has been shared as the address of the peer with whom the IdentityAttribute is shared is contained within their peer property. If an IdentityAttribute is shared by its owner with several peers, a corresponding number of AttributeForwardingDetails is generated. If the OwnIdentityAttribute is deleted, the associated AttributeForwardingDetails are deleted as well.

If an IdentityAttribute is shared by its owner, this not only leads to the creation of associated AttributeForwardingDetails for the owner of the IdentityAttribute, but also to the creation of a PeerIdentityAttribute for the peer with whom the IdentityAttribute was shared. The address of the owner of the IdentityAttribute is contained within its peer property. Furthermore, note that the id of a PeerIdentityAttribute is always the same as the id of the associated OwnIdentityAttribute. To ensure the privacy of an Identity’s data, the IdentityAttribute shared by its owner with a peer cannot be shared by that peer with a third party.

RelationshipAttributes

A RelationshipAttribute is used to store data that is relevant in the context of a Relationship between two Identities. Both Identities involved in the Relationship must agree to its creation. In the context of a single Relationship, each RelationshipAttribute has its unique key for identification. RelationshipAttributes can be shared with peers who are not involved in the Relationship in which the RelationshipAttribute exists as long as their confidentiality is not "private". Such sharing leads to the creation of ThirdPartyRelationshipAttributes.

For information on how to establish Relationships, refer to the Establish Relationships scenario documentation.

RelationshipAttribute value types

The RelationshipAttribute value types are used to define the type of the value property of a RelationshipAttribute. In order to fulfill various purposes, many such RelationshipAttribute value types are provided. Examples of RelationshipAttribute value types are ProprietaryString and ProprietaryEMailAddress. In contrast to IdentityAttributes, RelationshipAttributes are not divided into simple RelationshipAttributes and complex RelationshipAttributes depending on the value type. Nevertheless, the RelationshipAttribute value type Consent should be highlighted, as it differs slightly from the other RelationshipAttribute value types. Accordingly, with the Request persistent consent of peer scenario documentation, there is a separate guide for creating RelationshipAttributes with Consent as RelationshipAttribute value type.

LocalAttributes and RelationshipAttributes

From a technical perspective, a RelationshipAttribute is always stored as the content of a LocalAttribute. A LocalAttribute whose content is given by a RelationshipAttribute can be an OwnRelationshipAttribute, a PeerRelationshipAttribute or a ThirdPartyRelationshipAttribute. For the simple initial creation of a RelationshipAttribute within a given Relationship, the terms OwnRelationshipAttribute and PeerRelationshipAttribute are relevant. The term ThirdPartyRelationshipAttribute is used if an existing RelationshipAttribute from one Relationship is shared with a peer from another Relationship.

OwnRelationshipAttributes and PeerRelationshipAttributes

A RelationshipAttribute can only exist in the context of a Relationship and must therefore be stored locally for both Identities involved in the Relationship. Accordingly, the creation of a RelationshipAttribute corresponds to the creation of one LocalAttribute for its owner and one LocalAttribute for the peer with whom the owner has established the Relationship in whose context the RelationshipAttribute is to exist. The OwnRelationshipAttribute is the LocalAttribute of the owner of the RelationshipAttribute and the peer’s LocalAttribute is referred to as a PeerRelationshipAttribute.

Within the peer property of the OwnRelationshipAttribute, the address of the peer to whom the RelationshipAttribute’s owner has established the Relationship in whose context the RelationshipAttribute exists is specified. The PeerRelationshipAttribute is the peer’s LocalAttribute and forms the counterpart of the OwnRelationshipAttribute. The id of a PeerRelationshipAttribute is always the same as the id of the associated OwnRelationshipAttribute. Within the peer property of the PeerRelationshipAttribute, the address of the owner of the RelationshipAttribute is specified.

ThirdPartyRelationshipAttributes

Note that it is possible to share a RelationshipAttribute with peers who are not involved in the Relationship in which the RelationshipAttribute exists, provided that the confidentiality of the RelationshipAttribute is not "private". The sharing of a RelationshipAttribute with such a peer leads to the creation of associated AttributeForwardingDetails in the wallet of the Identity who has the source RelationshipAttribute. They contain the address of this peer within their peer property. If the source RelationshipAttribute is deleted, the associated AttributeForwardingDetails will be deleted as well. The source RelationshipAttribute is either an OwnRelationshipAttribute or a PeerRelationshipAttribute.

In the wallet of the peer with whom the underlying RelationshipAttribute of the source RelationshipAttribute was shared, a so-called ThirdPartyRelationshipAttribute is created. The initialAttributePeer property of the ThirdPartyRelationshipAttribute is set to the peer of the source RelationshipAttribute. The id of a ThirdPartyRelationshipAttribute is always the same as the id of the associated source RelationshipAttribute.

Attribute management options

The IdentityAttributes and RelationshipAttributes were previously introduced. Regardless of whether an Attribute is an IdentityAttribute or a RelationshipAttribute, various operations can be performed with Attributes. These are described on separate documentation pages. In the following, the Attribute management options are briefly described.

Create Attributes for yourself

Obviously, it is not possible to work with Attributes that have not yet been created. Therefore, the most important feature is the creation of Attributes for yourself.

Share Attributes with peer

Attributes can not only be managed locally, but can also be shared with peers. The Identity can either share IdentityAttributes about itself or RelationshipAttributes from a Relationship with another peer, provided the confidentiality allows for it.

Read Attributes from peer

If an Identity is interested in Attributes from another Identity and wants to query them, it can send a Request to read Attributes from the peer. In this case the recipient of the Request can determine the values of the requested Attributes. An example of a use case would be if a company needs additional information about a customer that it does not have yet.

Create Attributes for peer

Furthermore, it is possible to create Attributes for another Identity. In this case, the sender of the Request determines the value of the Attributes. For example if a school sends the students their certificates, then it is necessary to use Requests for creating Attributes.

Propose Attributes to peer

Lastly, if an Identity wants to propose an Attribute to a peer, it can send a Request that looks similar to the case where it wants to create an Attribute for the peer. However, the recipient of the Request has the possibility to answer with an Attribute whose content is determined by itself, similar to the case where the sender requests to read an Attribute from the peer. The difference to the ReadAttributeRequestItem is that an Identity already has information about a peer and wants them to be confirmed in order to use them. For example, a company may want to support a customer in setting up an enmeshed account by proposing Attributes derived from the company’s knowledge of the costumer.

Update Attributes by succession

If an Identity has created an Attribute that is owned by itself and is no longer valid, it has the option of updating the Attribute by succession. The peers with whom the Identity may have shared the Attribute can be notified about the update of the Attribute.

Delete Attributes

An Identity may have created an Attribute for itself or received an Attribute from a peer that it does not need any longer. In both cases, it can delete the Attribute. If an Identity has shared an Attribute with a peer, it can request the deletion of this Attribute from its recipient in order to withdraw their permission to use the Attribute. Of course, the associated emitted Attribute can be deleted, too.