Data Model Overview
The enmeshed data model can be divided into three parts:
- Transport types
- Local types
- Content types
The following diagram gives you an overview of all the existing types and how they are connected to each other. The subsequent chapters describe these types in more detail.
(note that you can click on each type in order to navigate to the paragraph with the corresponding description)
At a first glance the amount of types is overwhelming. But in the following chapters all of them are explained in detail.
Transport Types
Transport types like RelationshipTemplate
, Token
or File
are types that are “exchanged” between Identities via the Backbone. They are created and updated by the Transport Layer. In most cases they have a content
property, which contains the actual payload that should be transferred between the Identities. This payload is being encrypted when it is sent to the Backbone, and decrypted by the other Identity when it is received. The following sections describe the different Transport types and their properties.
Note that the properties of the types are the ones that exist locally (aka on the Connector/in the App). The Backbone does not necessarily know about them. The properties that only exist locally are marked accordingly in the tables below. Further there are properties that are confidential and are therefore encrypted before sent to the Backbone, in order to enable end-to-end encryption. Both kinds of these properties are marked accordingly in the “Remarks” column of the property tables below.
Token
Tokens can be used to save arbitrary structured data on the Backbone, which is encrypted with a random symmetric key. You can then pass the ID of the Token, together with the random key, to another Identity, which can then retrieve the token and decrypt it, e.g. inside of a QR Code, which you send to the recipient via letter. Tokens can be handy in a lot of scenarios, for example:
- You want to share secret information with someone you don’t have a Relationship with.
- The enmeshed App currently uses a Token to save a Backup of the Identity. ID and secret key are then encoded in a QR Code, which the user can print out and scan later in order to restore the Identity on a new device.
A Token has the following properties:
Name | Type | Description | Remarks |
---|---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each Token starts with the letters “TOK”. This way you can tell apart a Token ID from any other ID just by looking at the prefix. |
|
createdBy | string |
The Address of the Identity that created the Token. | |
createdByDevice | string |
The ID of the Device that created the Token. You can use this information to track back who exactly did what. | |
content | unknown |
The content of the Token. You can add whatever you want here. | will be encrypted before sent to the Backbone |
createdAt | string |
A timestamp that describes when the Token was created | |
expiresAt | string |
A timestamp that describes when the Token expires on the Backbone. An expired Token cannot be fetched from the Backbone anymore. However, the cached version of the Token on Connector and App will still be accesible. | |
secretKey | string |
The key with which the Token was encrypted. | saved only locally |
truncatedReference | string |
A base64 encoded string containing all information necessary for another Identity to load the Token. You can use it to share the Token with someone else. | saved only locally |
isEphemeral | boolean |
If set to true the Token will not be cached in the database and only displayed once. You will not be able to fetch this Token unless you remember its id and secretKey. |
RelationshipTemplate
A RelationshipTemplate serves two purposes:
- It represents the permission to establish a Relationship. When sending a Relationship request, the sender has to attach the ID of a valid RelationshipTemplate created by the recipient. Otherwise the Backbone blocks the Relationship request. And since the IDs are randomly generated, you can only obtain such an ID from the recipient.
- It can contain data which is of interest for the one who uses the RelationshipTemplate. The enmeshed App for example expects a RelationshipTemplate content which contains a
Request
which contains e.g. Attributes about the creator of the Template as well as queries for Attributes that the Template creator wants to receive together with the Relationship request.
Name | Type | Description | Remarks |
---|---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each RelationshipTemplate starts with the letters “RLT”. This way you can tell apart a RelationshipTemplate ID from any other ID just by looking at the prefix. |
|
isOwn | boolean |
true if the RelationshipTemplate was created by yourself, false if it was created by someone else. |
saved only locally |
createdBy | string |
The Address of the Identity that created the RelationshipTemplate. | |
createdByDevice | string |
The ID of the Device that created the RelationshipTemplate. You can use this information to track back who exactly did what. | |
createdAt | string |
A timestamp that describes when the RelationshipTemplate was created | |
content | RelationshipTemplateContent | unknown |
The content of the RelationshipTemplate. You can add whatever you want here. However, if it is intended for a User of the enmeshed App, RelationshipTemplateContent has to be used. Otherwise feel free to insert whatever you want or need. |
|
expiresAt | string |
A timestamp that describes when the RelationshipTemplate expires on the Backbone. An expired RelationshipTemplate cannot be fetched from the Backbone anymore. However, the cached version of the RelationshipTemplate on Connector and App will still be accesible. | will be encrypted before sent to the Backbone |
maxNumberOfAllocations | number | undefined |
Can be set to limit the number of allocations of this template. A RelationshipTemplate is allocated by another Identity when it is first retrieved by it from the Backbone. After this value is reached, the Backbone rejects each request of any new Identity that wants to retrieve it. Identities that already allocated it will still be able to retrieve it. | |
secretKey | string |
The key with which the RelationshipTemplate was encrypted. | saved only locally |
truncatedReference | string |
A base64 encoded string containing all information necessary for another Identity to load the RelationshipTemplate. You can use it to share the RelationshipTemplate with someone else. | saved only locally |
Relationship
A Relationship between two Identities is the prerequisite for them to exchange Messages. If there is no Relationship, the Backbone blocks all Messages that are tried to be sent. This ensures that you only receive Messages from Identities you know, so you are protected from any harmful Messages like spam or phishing mails.
Name | Type | Description | Remarks |
---|---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each Relationship starts with the letters “REL”. This way you can tell apart a Relationship ID from any other ID just by looking at the prefix. |
|
template | RelationshipTemplate |
The RelationshipTemplate that was used to establish this Relationship. | |
status | "Pending" | "Active" | "Rejected" | "Revoked" |
The status of this Relationship.
|
|
changes | RelationshipChange [] |
The history of changes made to this Relationship. You can find the definition of a RelationshipChange below. | |
peer | string |
The Address of the Identity with which you have this Relationship. | saved only locally |
RelationshipChange
Since a Relationship “belongs” to two Identities, each change on such a Relationship demands for the agreement of both parties. That’s where RelationshipChanges come into play. Whenever one party wants to make a change to the Relationship (like create or terminate it), it sends a RelationshipChange to the other party, which has to accept it in order for the change to take effect. If the other party doesn’t want to accept it, it can also reject it. And if the party that created the RelationshipChange changes its mind, it can revoke the RelationshipChange. The Backbone makes sure that a RelationshipChange can only be completed in one of those three ways (accepted, rejected, revoked). So for example if you try to accept a RelationshipChange that is already revoked, you will receive an error.
Name | Type | Description | Remarks |
---|---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each RelationshipChange starts with the letters “RCH”. This way you can tell apart a RelationshipChange ID from any other ID just by looking at the prefix. |
|
status | "Pending" |"Accepted" |"Rejected" |"Revoked" |
The current status of the RelationshipChange. | |
type | "Creation" |
The type of the RelationshipChange. Currently the only existing type is Creation . As soon as the termination of Relationships is supported, Termination will be a second RelationshipChange type. |
|
request | RelationshipChangeRequest |
Information about the request of the RelationshipChange. | |
response | RelationshipChangeResponse | undefined |
Information about the response of the RelationshipChange. |
Note that RelationshipChangeRequest and RelationshipChangeResponse have nothing to do with Requests and Responses, which we will discuss later.
RelationshipChangeRequest
Name | Type | Description | Remarks |
---|---|---|---|
createdBy | string |
The Address of the Identity that created the RelationshipChangeRequest. | |
createdByDevice | string |
The ID of the Device that created the RelationshipChangeRequest. You can use this information to track back who exactly did what. | |
createdAt | string |
A timestamp that describes when the RelationshipChangeRequest was created | |
content | RelationshipCreationChangeRequestContent | unknown |
The content of the RelationshipChangeRequest. You can add whatever you want here. However, if the other party uses the enmeshed App, and the type of the RelationshipChange is Creation , RelationshipCreationChangeRequestContent has to be used. Otherwise feel free to insert whatever you want or need. |
will be encrypted before sent to the Backbone |
RelationshipChangeResponse
Name | Type | Description | Remarks |
---|---|---|---|
createdBy | string |
The Address of the Identity that created the RelationshipChangeResponse. | |
createdByDevice | string |
The ID of the Device that created the RelationshipChangeResponse. You can use this information to track back who exactly did what. | |
createdAt | string |
A timestamp that describes when the RelationshipChangeResponse was created | |
content | unknown |
The content of the RelationshipChangeResponse. You can add whatever you want here. Since the enmeshed App doesn’t expect any special content here, there is no need to watch out. | will be encrypted before sent to the Backbone |
Message
A Message is a piece of data that can be sent to one or more recipients. The sender is completely free in what the content of the Message looks like. Though in order to enable a normalized communication, enmeshed defines some content
structures for Messages, and in the future there will be more of those. Consider that the enmeshed App only supports Messages with such a normalized content
. Currently there are:
You can read more details about each of these in the corresponding sections of the “Content Types” chapter.
But if you are communicating with another Connector, feel free to settle on any content
structure that fits your needs.
Name | Type | Description | Remarks |
---|---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each Message starts with the letters “MSG”. This way you can tell apart a Message ID from any other ID just by looking at the prefix. |
|
content | unknown |
The content of the Message. You can add whatever you want here. However, if it is intended for a User of the enmeshed App, use either Mail , Request , Response or Notification . Otherwise feel free to insert whatever you want or need. |
will be encrypted before sent to the Backbone |
createdBy | string |
The Address of the Identity that created the Message. | |
createdByDevice | string |
The ID of the Device that created the Message. You can use this information to track back who exactly did what. | |
recipients | Recipient [] |
An array of recipients of this Message. | |
createdAt | string |
A timestamp that describes when the Message was created | |
attachments | string[] |
An array of File IDs you want to attach to your Message. You receive the File ID after you uploaded a file to the Backbone. By attaching a File to a Message, you share the secret key used to encrypt/decrypt the File, which cannot be undone. | |
isOwn | boolean |
Indicates whether you are the sender (true ) or recipient (false ) of the Message. |
|
wasReadAt | string | undefined |
A timestamp indicating when the Message was firstly read. If a Message is marked as unread, this will be undefined . If a Message is read again, after having marked it as unread, the timestamp is updated. However, if a Message marked as read is read again, it won’t be updated. |
Recipient
Name | Type | Description | Remarks |
---|---|---|---|
address | string |
The Address of the recipient of the Message. | |
relationshipId | string |
The ID of the Relationship between the recipient and the sender of the Message. | saved only locally |
receivedAt | string | undefined |
A timestamp that describes when the recipient retrieved the Message from the Backbone. undefined when the Message wasn’t received yet. Caution: “received” does not mean that it was read, so don’t mix this up with a read receipt. |
|
receivedByDevice | string | undefined |
The ID of the Device that first retrieved the Message. undefined when the Message wasn’t received yet. This is of no interest for the sender of the Message, but rather for the recipient itself, since they can use it for audit purposes. sender |
File
The Backbone allows you to upload files, which are saved as - you guessed it - Files
.
Name | Type | Description | Remarks |
---|---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each File starts with the letters “FIL”. This way you can tell apart a File ID from any other ID just by looking at the prefix. |
|
createdAt | string |
A timestamp that describes when the File was created | |
createdBy | string |
The Address of the Identity that created the File. | |
createdByDevice | string |
The ID of the Device that created the File. You can use this information to track back who exactly did what. | |
expiresAt | string |
A timestamp that describes when the File expires on the Backbone. An expired File cannot be fetched from the Backbone anymore. However, the cached version of the File on Connector and App will still be accesible. | |
filename | string |
The name of the file as it was on the device that uploaded it. | will be encrypted before sent to the Backbone |
filesize | number |
The size of the plaintext file in bytes. | will be encrypted before sent to the Backbone |
mimetype | string |
The mimetype of the file. | will be encrypted before sent to the Backbone |
title | string |
A human readable title of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone |
description | string | undefined |
A human readable description of the file, which can be defined when uploading the File. | will be encrypted before sent to the Backbone |
secretKey | string |
The key that was used to encrypt the File. | saved only locally |
isOwn | boolean |
true if the File was created by yourself, false if it was created by someone else. |
saved only locally |
truncatedReference | string |
A base64 encoded string containing all information necessary for another Identity to load the File. You can use it to share the File with someone else. | saved only locally |
A File further has its content, of course. But since this is not a JSON property, it is not included in this table. You can download the content of the File separately.
Local Types
In addition to the types that are shared between Identities via the Backbone, there are certain types that only exist within one Identity. These types usually contain metadata about Content types that should not be transferred to other Identities. They are created and updated by the Consumption Layer.
Currently there are three main Local types:
- LocalRequest
- LocalNotification
- LocalAttribute
Each of them further describes some sub types.
This chapter explains all of those types, together with their properties.
LocalRequest
A LocalRequest contains the local metadata for a Request.
Name | Type | Description |
---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each LocalRequest starts with the letters “REQ”. This way you can tell apart a LocalRequest ID from any other ID just by looking at the prefix. |
isOwn | boolean |
true if you sent the Request, false if you received it. |
peer | string |
The Identity that sent you the corresponding Request/that you sent the Request to. |
createdAt | string |
A timestamp that describes when the LocalRequest was created |
status | LocalRequestStatus |
The current status of the Request. See below for a list of all possible values. |
content | Request |
The actual Content object this LocalRequest defines the metadata for. |
source | LocalRequestSource | undefined |
Information about the Transport object with which the Request came in/was sent. This property is undefined if the Request is not sent yet. |
response | LocalResponse | undefined |
Metadata + Content object of the response. If there is no response yet, this property is undefined . |
LocalRequestStatus
Depending on whether it is an incoming or an outgoing Request, there can be different statuses. The following state diagram shows which status exists in both cases and when there are transitions from one state to another:
- Draft
- This status only exists for outgoing Requests. It means that the LocalRequest was created, but not yet sent.
- Open
- In case of an outgoing Request,
Open
means that the Request was sent. The transition toOpen
happens automatically when you send the Request with a Message. - In case of an incoming Request,
Open
means that the LocalRequest was received. - DecisionRequired
- After the prerequisites of the Request and all of its RequestItems were checked, a decision can be made. At first, the Decider Module tries to make an automatic decision. It therefore checks all LocalRequests in status
DecisionRequired
. - ManualDecisionRequired
- If the Decider Module cannot make a decision, it moves the LocalRequest to
ManualDecisionRequired
. When the LocalRequest is in this status, it’s the User’s turn to decide whether they want to accept or reject the Request. - Decided
- When the User or the Decider Module accepts or rejects the Request, the Response and ResponseItems are generated based on the passed parameters. This Response is saved in the
response
property of theLocalRequest
, but not yet sent. - Completed
- In case of an incoming Request, the Runtime Module listens to an Event saying that a Request moved to status
Decided
. It then checks on which way the Request was received (Message/RelationshipTemplate) and sends the Response on the corresponding way (by sending a message or creating a Relationship). After the Response was successfully sent, it moves the LocalRequest toCompleted
. - In case of an outgoing Request, the Runtime Module listens to the
MessageReceivedEvent
and checks the content of the sent Message for a Response. If there is one, it moves the corresponding LocalRequest toCompleted
. - Expired
- When the timestamp in
expiresAt
of a Request is reached, the Request automatically moves to the statusExpired
.
LocalRequestSource
With the information in this type you can clearly identify the Transport object the Request was sent/received in. Currently there are only two possibilities: Message and RelationshipTemplate.
Name | Type | Description |
---|---|---|
type | "Message" | "RelationshipTemplate" |
The type of Transport object the Request was sent/received in. |
reference | string |
The ID of the Transport object the Request was sent/received in. |
LocalResponse
When a LocalRequest is decided/received, a Local Response is generated, which contains the Response, together with some metadata.
Name | Type | Description |
---|---|---|
createdAt | string |
A timestamp that describes when the LocalResponse was created |
content | Response |
The actual Content object this Local Response defines the metadata for. |
source | LocalResponseSource | undefined |
Information about the Transport object with which the Response came in/was sent. This property is undefined if the Response is not sent/received yet. |
LocalResponseSource
With the information in this type you can clearly identify the Transport object the Response was sent/received in. Currently there are only two possibilities: Message and RelationshipChange.
Name | Type | Description |
---|---|---|
type | "Message" | "RelationshipChange" |
The type of Transport object the Response was sent/received in. |
reference | string |
The ID of the Transport object the Response was sent/received in. |
LocalNotification
A LocalNotification contains the local metadata for a Notification.
Name | Type | Description |
---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each LocalNotification starts with the letters “NOT”. This way you can tell apart a LocalNotification ID from any other ID just by looking at the prefix. |
isOwn | boolean |
true if you sent the Notification, false if you received it. |
peer | string |
The Identity that sent you the corresponding Notification/that you sent the Notification to. |
createdAt | string |
A timestamp that describes when the LocalNotification was created |
status | LocalNotificationStatus |
The current status of the Notification. See below for a list of all possible values. |
content | Notification |
The actual Content object this LocalNotification defines the metadata for. |
source | LocalNotificationSource |
Information about the Transport object with which the Notification came in/was sent. |
receivedByDevice | string | undefined |
The ID of the device that received the Notification. For reasons of consistence, the Notification can only be processed by this device. |
LocalNotificationStatus
Depending on whether it is an incoming or an outgoing Notification, there can be different statuses.
- Sent
- This is the only valid status on sender side. If a Notification is sent and, therefore, a LocalNotification is created, its status will be set to
Sent
. - Open
- Receiving a Notification, a LocalNotification is created with status
Open
. - Completed
- After receiving a Notification, its items will be processed internally. If all processes finish successfully, the status of the LocalNotification will be set to
Completed
. - Error
- If an error occurs while processing the items of a received Notification, the status of the LocalNotification will be set to
Error
.
LocalNotificationSource
With the information in this type you can clearly identify the Transport object the Notification was sent/received in. Currently, the only possibility for transmitting Notifications are Messages.
Name | Type | Description |
---|---|---|
type | “Message” | The type of Transport object the Notification was sent/received in. So far, Notifications can only be transmitted via Messages. |
reference | string |
The id of the Transport object the Notification was sent/received in. |
LocalAttribute
A LocalAttribute contains the local metadata for an Attribute. In the context of IdentityAttributes, there are three situations a LocalAttribute is created in the database:
- The Identity maintains an Attribute about itself (e.g. sets its first name). We call such an unshared LocalAttribute “RepositoryAttribute”. Its
shareInfo
property is undefined. - The Identity shares an Attribute of itself with another Identity (e.g. sends it in a Request). In that case, a copy of the original LocalAttribute is created, where the
shareInfo
property is set. We call this LocalAttribute an “own shared IdentityAttribute”. - The Identity receives an Attribute from another Identity (e.g. receives it in a Request). In that case a new LocalAttribute is created, where the
shareInfo
is set. We call this LocalAttribute a “peer shared IdentityAttribute”.
In contrast, RelationshipAttributes always exist in the context of a Relationship. Thus, it is not possible for an Identity to have an unshared RelationshipAttribute.
- We refer to the LocalAttribute of the owner as “own shared RelationshipAttribute”.
- The peer’s LocalAttribute we referred to as “peer shared RelationshipAttribute”.
Name | Type | Description |
---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each LocalAttribute starts with the letters “ATT”. This way you can tell apart a LocalAttribute ID from any other ID just by looking at the prefix. |
parentId | string | undefined |
If the Attribute referenced by this LocalAttribute is a component of a composite Attribute, the parentId property is set to the id of the composite Attribute. Example: if a LocalAttribute is created with the content StreetAddress , for each property of the StreetAddress an additional LocalAttribute is created. And each of these will have parentId set to the id of the LocalAttribute for the StreetAddress . |
createdAt | string |
A timestamp that describes when the LocalAttribute was created |
content | IdentityAttribute | RelationshipAttribute |
The actual Content object this LocalAttribute defines the metadata for. |
succeeds | string | undefined |
The ID of the LocalAttribute that succeeds the current one. |
succeededBy | string | undefined |
The ID of the LocalAttribute that is succeeded by the current one. |
shareInfo | LocalAttributeShareInfo | undefined |
Information about the peer this LocalAttribute was received from/shared with, as well as via which LocalRequest it was received/sent. If the LocalAttribute refers to a RepositoryAttribute, this property is undefined . |
deletionInfo | LocalAttributeDeletionInfo | undefined |
Information about whether the counterpart of a shared Attribute is to be deleted or was deleted by the peer of the Relationship, as well as the point in time of that deletion. |
LocalAttributeShareInfo
The LocalAttributeShareInfo helps to keep track of how the LocalAttribute was received/sent, from whom it was received/who sent it, as well as which LocalAttribute it was copied from. For example, this enables us to track back who we shared a certain IdentityAttribute with, so we are able to notify each of those peers when changing it. The Attribute can be either transmitted via Request or Notification. Hence, only one of requestReference
and notificationReference
can be set.
Name | Type | Description |
---|---|---|
peer | string |
The Address of the Identity the LocalAttribute was received from/shared with. |
requestReference | string | undefined |
The id of the LocalRequest the LocalAttribute was received in/sent with. If this is set, notificationReference must be undefined. |
notificationReference | string | undefined |
The id of the LocalNotification the LocalAttribute was received in/sent with. If this is set, requestReference must be undefined. |
sourceAttribute | string | undefined |
If the LocalAttribute is an own shared IdentityAttribute, then this property contains the id of the RepositoryAttribute it was copied from. Also, if a RelationshipAttribute is shared with a third party, i.e. in the context of a Relationship that is different to the one the RelationshipAttribute was initially created in, this ThirdPartyRelationshipAttribute will link to the source RelationshipAttribute. Note that sourceAttribute is only defined for the peer who also has the Attribute this property links to. Regarding IdentityAttributes this is the owner. For ThirdPartyRelationshipAttributes it is the peer who is in the Relationship the source RelationshipAttribute is copied from. |
LocalAttributeDeletionInfo
The LocalAttributeDeletionInfo holds information about the deletion status of the counterpart of a shared Attribute, as well as the point in time of that deletion.
If the Attribute’s owner requested the deletion of a shared Attribute via a DeleteAttributeRequestItem from the peer and they accepted using the AcceptDeleteAttributeRequestItemParameters, the deletionStatus
of the peer shared Attribute of the peer will be set to "ToBeDeleted"
and its deletionDate
will be set to the deletionDate
the peer sent in their Response.
Accordingly, the deletionStatus
of the own shared Attribute of the owner will move to "ToBeDeletedByPeer"
with the same deletionDate
.
Once the peer shared Attribute is deleted by the peer, a PeerSharedAttributeDeletedByPeerNotificationItem is sent to the owner, where the deletionStatus
of the own shared Attribute is set to "DeletedByPeer"
with the current time stamp as deletionDate
.
Likewise, if the owner deletes their own shared Attribute, before the peer deleted their corresponding peer shared Attribute, an OwnSharedAttributeDeletedByOwnerNotificationItem is sent to the peer.
If the deletionInfo
of the peer was undefined before, the deletionStatus
will be set to "DeletedByOwner"
with the current time stamp as deletionDate
.
However, if the deletionInfo
was defined before with "ToBeDeleted"
as deletionStatus
, it will remain unchanged, such that the peer will be able to delete their peer shared Attribute as planned.
This will be the case, if the peer already accepted the DeleteAttributeRequestItem for this particular Attribute.
Name | Type | Description |
---|---|---|
deletionStatus | "ToBeDeleted" | "ToBeDeletedByPeer" | "DeletedByOwner" | "DeletedByPeer" |
The deletion status of the peer’s counterpart of the shared Attribute. For own shared Attributes it may only be set to "ToBeDeletedByPeer" or "DeletedByPeer" , whereas for peer shared Attributes only the values "ToBeDeleted" and "DeletedByOwner" are allowed. |
deletionDate | string |
The point in time an upcoming deletion is planned (for the deletionStatus "ToBeDeleted" or "ToBeDeletedByPeer" ) or a completed deletion has been notified (for "DeletedByOwner" or "DeletedByPeer" ). |
LocalAttributeListener
A LocalAttributeListener is created when you accept an incoming Request with a RegisterAttributeListenerRequestItem
. It is used to keep track of which Attribute Listeners currently exist and what they are listening for.
Name | Type | Description |
---|---|---|
id | string |
Unique identifier of this object. Remark: the ID of each LocalAttributeListener starts with the letters “ATL”. This way you can tell apart a LocalAttributeListener ID from any other ID just by looking at the prefix. |
query | IdentityAttributeQuery | ThirdPartyRelationshipAttributeQuery |
The query the Attribute that is listened to must match. Note that you cannot send a RelationshipAttributeQuery here, because it doesn’t make sense: by definition, both parties know about a RelationshipAttribute right from the beginning, because one party requests its creation, and the other one accepts it. |
peer | string |
The Address of the peer that requested the Attribute Listener. |
Content Types
Content Types can be seen as a data contract between Identities. The medium through which this data is exchanged are the Transport types (e.g. Messages, Tokens, …). This chapter shows all the Content types and describes their intended usage.
Request
A Request allows you to ask another Identity to do something. What this “something” is depends on which of the so called RequestItems were added to the Request (e.g. CreateAttributeRequestItem
, ReadAttributeRequestItem
, …). The Request is then sent to the peer via Message or RelationshipTemplate. The peer can then review the Request and decide whether they want to accept or reject it. And if they accept it, they can even choose which of the Items they want to accept. You can also put multiple Items into a group in order to ensure that they can only be accepted/rejected as a unit.
Name | Type | Description |
---|---|---|
@type | “Request” | |
id | string | undefined |
Unique identifier of this object. This property is undefined if the Request is inside of a RelationshipTemplate. Remark: the ID of each Request starts with the letters “REQ”. This way you can tell apart a Request ID from any other ID just by looking at the prefix. |
title | string | undefined |
An optional, human readable title for the Request. |
description | string | undefined |
An optional, human readable description for the Request. |
expiresAt | string | undefined |
A timestamp that describes when the Request expires on the Backbone. An expired Request cannot be fetched from the Backbone anymore. However, the cached version of the Request on Connector and App will still be accesible. |
items | ( RequestItemGroup | \*RequestItem )[] |
An array of RequestItems and Groups that are part of the Request. There must be at least one Item or Group per Request. |
metadata | string | undefined |
Optional custom metadata that can be sent together with the Request. This property is meant purely for developers who integrate with enmeshed. They can write for example some kind of key into this property, which can be used later to identify the content of this Request. |
RequestItems
RequestItems can be sent inside of a Request and specify what should be done when the Request is accepted.
AuthenticationRequestItem
Name | Type | Description |
---|---|---|
@type | "AuthenticationRequestItem" |
Specifies the type of the RequestItem for internal processing. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
ConsentRequestItem
Name | Type | Description |
---|---|---|
@type | "ConsentRequestItem" |
Specifies the type of the RequestItem for internal processing. |
consent | string |
The textual consent the user needs to give. This is different to the title and description of the RequestItem, as the consent would be the actual statement the user agrees to. |
link | string | undefined |
A valid URL linking to a website which contains more information, like the EULA or privacy terms. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
CreateAttributeRequestItem
Name | Type | Description |
---|---|---|
@type | "CreateAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attribute | IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to create for the peer within the Identity of the peer. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
DeleteAttributeRequestItem
Name | Type | Description |
---|---|---|
@type | "DeleteAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attributeId | string |
The id of the own shared Attribute you wish for the peer to delete. This will match the id of the corresponding peer shared Attribute at the peer’s side. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
FreeTextRequestItem
Name | Type | Description |
---|---|---|
@type | "FreeTextRequestItem" |
Specifies the type of the RequestItem for internal processing. |
freeText | string |
The free text you want to send to the peer. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
ProposeAttributeRequestItem
Name | Type | Description |
---|---|---|
@type | "ProposeAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attribute | IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. |
query | IdentityAttributeQuery | RelationshipAttributeQuery | IQLQuery |
The structured query of the Attribute the sender would like to receive. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
ReadAttributeRequestItem
Name | Type | Description |
---|---|---|
@type | "ReadAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
query | IdentityAttributeQuery | RelationshipAttributeQuery | ThirdPartyRelationshipAttributeQuery | IQLQuery |
The structured query of the Attribute the sender would like to receive. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
RegisterAttributeListenerRequestItem
Name | Type | Description |
---|---|---|
@type | "RegisterAttributeListenerRequestItem" |
Specifies the type of the RequestItem for internal processing. |
query |
IdentityAttributeQuery | ThirdPartyRelationshipAttributeQuery |
The structured query of the Attribute the sender would like to query. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
ShareAttributeRequestItem
Name | Type | Description |
---|---|---|
@type | "ShareAttributeRequestItem" |
Specifies the type of the RequestItem for internal processing. |
attribute | IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to share. This is not the LocalAttribute but the content data structure of the Attribute. The owner of the Attribute which should be shared can only be the sender Identity. |
sourceAttributeId | string |
The id of the LocalAttribute which is the source of the shared Attribute. This will be used later to reference the sourceAttribute from its shared copy. |
title | string | undefined |
An optional, human readable title for the RequestItem. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
The metadata property can be used to provide arbitrary JSON content by the sender of the request. The metadata is not processed by enmeshed. It is a great way to use your own process descriptors at the time of sending the request which helps you identify the correct internal process at the time of receiving the response. |
mustBeAccepted | boolean |
The mandatory mustBeAccepted property is used to differentiate between required and optional RequestItems within the Request. In other words, if the peer Identity may or may not decide to ignore this specific RequestItem. If set to true, the peer cannot accept the Request without accepting this item. For example, some Attributes are mandatory for the business process and thus the respective RequestItems must be accepted (mustBeAccepted = true). A consent to a newsletter is optional and thus only can be accepted (mustBeAccepted = false). Keep in mind that if the RequestItem is inside of a RequestItem Group, then this flag takes effect only when the Group is accepted. So as long as the Group is not accepted, the Item does not have to be accepted either. |
requireManualDecision | boolean | undefined |
To block the automated acceptance of Requests, the requireManualDecision property can be set to true. The default is, that each RequestItem may be automatically processed on the peer side. If the sender would like to have an enforced manual acceptance step the requireManualDecision property can be set to true. |
RequestItemGroup
Name | Type | Description |
---|---|---|
@type | "RequestItemGroup" |
|
title | string | undefined |
An optional, human readable title for the RequestItem Group. |
description | string | undefined |
An optional, human readable description for the RequestItem. |
metadata | object | undefined |
Optional metadata that can be sent together with this RequestItem. The intended usage is the same as of the metadata property of the Request. |
mustBeAccepted | boolean |
If set to true , then this RequestItem Group has to be accepted when the Request is accepted. |
items | *RequestItem [] |
The items inside of this Group. There has to be at least one RequestItem per Group. Note that we do not support nested Groups at the moment. If you need this feature, you can raise a feature request. |
Response
Name | Type | Description |
---|---|---|
@type | "Response" |
|
result | "Accepted" | "Rejected" |
Whether the Response was accepted or rejected by the recipient of the Request. |
requestId | string |
The id of the Request this Response belongs to. The Sender of the Request needs this information to map the Response to the corresponding Request. |
items | ( ResponseItemGroup \| ResponseItem )[] |
An array of Response Items and Groups that are part of the Response. For each RequestItem (Group) of the Request, there must be one Response Item (Group) in the Response. Note that the indices have to be the same for matching Request and Response Items. |
ResponseItems
Response Items are sent inside of a Response. They contain the response data that is sent by the recipient of the Request. There are three different kinds of Response Items: AcceptResponseItem
, RejectResponseItem
and ErrorResponseItem
. Depending on the actual RequestItem, there can be different derivations of these three items. For example, in case of a CreateAttributeRequestItem
, there is a special CreateAttributeAcceptResponseItem
, while for an AuthenticationRequestItem
, the AcceptResponseItem
can be used, because there is no additional information necessary next to whether it was accepted or rejected.
AcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "AcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
CreateAttributeAcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "CreateAttributeAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
attributeId | string |
The id of the created LocalAttribute. |
DeleteAttributeAcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "DeleteAttributeAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
deletionDate | string |
The timestamp of when the peer will delete the Attribute. |
FreeTextAcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "FreeTextAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
freeText | string |
The free text that is used to answer the RequestItem. |
ProposeAttributeAcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "ProposeAttributeAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
attributeId | string |
The id of the created LocalAttribute. |
attribute | IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute to propose for the peer as the queried Attribute. The owner of the Attribute which is proposed can only be the recipient Identity. |
ReadAttributeAcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "ReadAttributeAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
attributeId | string |
The id of the returned LocalAttribute. |
attribute | IdentityAttribute | RelationshipAttribute |
The IdentityAttribute or RelationshipAttribute that will be shared to the peer. |
RegisterAttributeListenerAcceptResponseItem
Name | Type | Description |
---|---|---|
@type |
"RegisterAttributeListenerAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
listenerId |
string |
The id of the created AttributeListener. |
ShareAttributeAcceptResponseItem
Name | Type | Description |
---|---|---|
@type | "ShareAttributeAcceptResponseItem" |
The type of the ResponseItem. |
result | "Accepted" |
The only possible value here is the string "Accepted" . |
attributeId | string |
The id of the shared LocalAttribute. |
RejectResponseItem
Name | Type | Description |
---|---|---|
@type | "RejectResponseItem" |
The type of the ResponseItem. |
result | "Rejected" |
The only possible value here is the string "Rejected" . |
code | string | undefined |
A code telling the sender about the reason for the rejection. |
message | string | undefined |
A human readable message with details about the rejection. |
ErrorResponseItem
The ErrorResponseItem
is only created by the enmeshed Runtime, in case something happens which hinders you from further processing of the RequestItem. It will never be created manually. The properties are:
Name | Type | Description |
---|---|---|
@type | "ErrorResponseItem" |
The type of the ResponseItem. |
result | "Error" |
The only possible value here is the string "Error" . |
code | string |
An error code telling the sender about the kind of error that occurred. |
message | string |
A human readable error message with details about the error. |
ResponseItemGroup
Name | Type | Description |
---|---|---|
@type | "ResponseItemGroup" |
|
items | ResponseItem [] |
The items inside of this Group. For each RequestItem of the RequestItem Group, there must be one Response Item in the Response Item Group. Note that the indices have to be the same for matching Request and Response Items. |
ResponseWrapper
The ResponseWrapper is a wrapper around the Response that is sent by the recipient of the Request. It contains the Response itself, but also some additional information that is required for the Request to be processed correctly.
Name | Type | Description |
---|---|---|
@type | "ResponseWrapper" |
|
requestId | string |
The id of the Request this Response belongs to. |
requestSourceReference | string |
The reference to the Message or RelationshipTemplate the Request was received with. |
requestSourceType | "Message" | "RelationshipTemplate" |
Specifies if the Request was transferred via Message or RelationshipTemplate. |
response | Response |
The Response that is sent by the recipient of the Request. |
Notification
Notifications provide you with the possibility to notify a peer about something, e.g. the succession of one of your Attributes. However, unlike Requests they don’t offer the option to make a decision whether or not they want to accept this change. In the example of Attribute succession, the peer can not decide to accept or reject the updated value, but is simply informed about it.
Name | Type | Description |
---|---|---|
@type | "Notification" |
|
id | string |
Unique identifier of this object. Remark: the ID of each Notification starts with the letters “NOT”. This way you can tell apart a Notification ID from any other ID just by looking at the prefix. |
items | NotificationItem[] |
An array of NotificationItems that are part of the Notification. There must be at least one Item per Notification. |
NotificationItems
NotificationItems are sent inside a Notification and specify which processes should be triggered when receiving the Notification.
OwnSharedAttributeDeletedByOwnerNotificationItem
If a peer has shared one of their Attributes with you and deletes their own shared Attribute, an OwnSharedAttributeDeletedByOwnerNotificationItem will be sent to you.
Internally, for your corresponding peer shared Attribute the deletionInfo.deletionStatus
will be set to "DeletedByOwner"
if it wasn’t set to "ToBeDeleted
before.
Name | Type | Description |
---|---|---|
@type | "OwnSharedAttributeDeletedByOwnerNotificationItem" |
|
attributeId | string |
The id of the own shared Attribute that was deleted by the owner. It matches the id of the corresponding peer shared Attributes of the recipient. |
PeerSharedAttributeDeletedByPeerNotificationItem
If you have shared one of your Attributes with a peer and they delete their peer shared Attribute, a PeerSharedAttributeDeletedByPeerNotificationItem will be sent to you.
Internally, for your corresponding own shared Attribute the deletionInfo.deletionStatus
will be set to "DeletedByPeer"
.
Name | Type | Description |
---|---|---|
@type | "PeerSharedAttributeDeletedByPeerNotificationItem" |
|
attributeId | string |
The id of the peer shared Attribute that was deleted by the peer. It matches the id of the corresponding own shared Attributes of the recipient. |
PeerSharedAttributeSucceededNotificationItem
A PeerSharedAttributeSucceededNotificationItem will be sent, if an Attribute, a peer shared with you, was succeeded by them and they choose to notify you about it. Internally, the succeeded version will then be created at your side as successor for your previously received Attribute.
Name | Type | Description |
---|---|---|
@type | "PeerSharedAttributeSucceededNotificationItem" |
|
predecessorId | string |
The id of the LocalAttribute that was succeeded |
successorId | string |
The id of the LocalAttribute it was succeeded by |
successorContent | IdentityAttribute | RelationshipAttribute |
The updated content of the LocalAttribute |
ThirdPartyOwnedRelationshipAttributeDeletedByPeerNotificationItem
If you have shared a RelationshipAttribute, that is not owned by you, with a peer from a different Relationship and that peer deletes their third party owned RelationshipAttribute, a ThirdPartyOwnedRelationshipAttributeDeletedByPeerNotificationItem will be sent to you.
Internally, for your corresponding third party owned RelationshipAttribute the deletionInfo.deletionStatus
will be set to "DeletedByPeer"
.
Name | Type | Description |
---|---|---|
@type | "ThirdPartyOwnedRelationshipAttributeDeletedByPeerNotificationItem" |
|
attributeId | string |
The id of the third party owned RelationshipAttribute that was deleted by the peer. The id of the third party owned RelationshipAttribute of the sender matches the one of the recipient. |
Attributes
An Attribute is some piece of information about an Identity itself (e.g. its name, address, birth date, etc.) or about an Identity in the context of a Relationship (e.g. the customer id the of the user the Relationship). Since the two scenarios differ quite a lot, there are two different types for them: IdentityAttribute and RelationshipAttribute.
IdentityAttribute
IdentityAttributes describe an Identity itself. Their values are strongly normalized. There is a list of available values here.
Name | Type | Description |
---|---|---|
@type | "IdentityAttribute" |
|
owner | string |
The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. |
validFrom | string | undefined |
The date from which on the Attribute is valid. Could be in the future if the Attribute is not yet valid. |
validTo | string | undefined |
The date until this Attribute is valid. Could be in the past if the Attribute is already expired. |
value | IdentityAttributeValue |
The Attribute’s value. |
tags | string[] | undefined |
To specify additional information. |
RelationshipAttribute
RelationshipAttributes describe an Identity in the context of a Relationship. While there are some types that can be used as a value for a RelationshipAttribute, these types are rather generic (e.g. ProprietaryString
, ProprietaryInteger
, …).
Name | Type | Description | |
---|---|---|---|
@type | "RelationshipAttribute" |
||
owner | string |
The Identity that owns this Attribute. Only the owner of an Attribute is allowed to change it after its creation. | |
validFrom | string | undefined |
The date from which on the Attribute is valid. Could be in the future if the Attribute is not yet valid. | |
validTo | string | undefined |
The date until this Attribute is valid. Could be in the past if the Attribute is already expired. | |
key | string |
An arbitrary key that is set by the creator of this Attribute. It is used to identify the Attribute in a query, especially by a third party. Example: you could set something like customerId in case of a customer id. |
|
isTechnical | boolean | undefined |
Defines whether the RelationshipAttribute contains data that is actually relevant for the user (isTechnical=false ) or whether it should be hidden in the UI (isTechnical=true ). |
|
value | RelationshipAttributeValue |
The Attribute’s value. | |
confidentiality | "public" | "protected" | "private" |
When this property is set to "private" , it means that third parties are not able to query this RelationshipAttribute. It therefore only exists in the Relationship it was created in. If the confidentiality is "protected" , third parties can query the RelationshipAttribute, but the App shows a warning saying that you should only share it with someone you trust. If the confidentiality is "public" , everybody can query the Attribute, without anything special to happen. |
AttributeQueries
One of the main features of enmeshed is sharing Attributes. For this, an Identity either proactively sends its Attributes to a peer. Or, if let’s say a company wants to know the birth date of its customer, it can ask for it. Depending on the exact use case, the latter can be achieved with one of a bunch of RequestItems, like for example a ReadAttributeRequestItem
, or a CreateAttributeListenerRequestItem
. All of them have in common that they define a query
property, which contains either an IdentityAttributeQuery
or a RelationshipAttributeQuery
.
IdentityAttributeQuery
An IdentityAttributeQuery
is used to query for IdentityAttributes. For that, it defines the following properties:
Name | Type | Description |
---|---|---|
@type | "IdentityAttributeQuery" |
|
validFrom | string | undefined |
The start date of the time frame the returned Attribute should be valid in. |
validTo | string | undefined |
The end date of the time frame the returned Attribute should be valid in. |
valueType | string |
The type of value that should be queried, e.g. "StreetAddress" , "BirthDate" or "Nationality" . |
tags | string[] | undefined |
To specify additional information. |
You can only query IdentityAttributes owned by the recipient of the query.
RelationshipAttributeQuery
There are cases in which you want to query some data from your peer that is not an IdentityAttribute. An example for this is when an electricity provider asks for the electric meter number of a new customer. Since this information is only relevant in the context of the Relationship, an IdentityAttribute wouldn’t make any sense here. That’s why you would send a RelationshipAttributeQuery
. Its properties are:
Name | Type | Description |
---|---|---|
@type | "RelationshipAttributeQuery" |
|
validFrom | string | undefined |
The start date of the time frame the returned Attribute should be valid in. |
validTo | string | undefined |
The end date of the time frame the returned Attribute should be valid in. |
key | string |
The key of the RelationshipAttribute that should be queried. |
owner | string |
The owner of the queried RelationshipAttribute. |
attributeCreationHints | RelationshipAttributeCreationHints |
Contains information about the value that will be created, like the value type or its confidentiality. |
RelationshipAttributeCreationHints
Name | Type | Description |
---|---|---|
title | string |
A short text describing the purpose of the Attribute that is about to be created. |
description | string | undefined |
A long text describing the purpose of the Attribute that is about to be created. |
valueType | string |
The value type of the Attribute to be created (e.g. "ProprietaryInteger" , "ProprietaryString" , …) |
confidentiality | "public" |"protected" |"private" |
The confidentiality of the Attribute to be created. See RelationshipAttribute for a more detailed description of confidentialities. |
valueHints | ValueHints | undefined |
Hints for validating the value, e.g. a regular expression or a min/max length. |
ValueHints
Name | Type | Description |
---|---|---|
@type | "ValueHints" |
|
editHelp | string | undefined |
A help text you can use to describe the purpose of the Attribute. |
min | number | undefined |
In case of a string: the minimum length of the string. In case of an integer: the minimum value. |
max | number | undefined |
In case of a string: the maximum length of the string. In case of an integer: the maximum value. |
pattern | string | undefined |
A regular expression that is used to validate the value. Only applicable if the value is a string. |
values | ValueHintsValue [] | undefined |
An array of allowed values. |
defaultValue | string | number | boolean | undefined |
The default value that is used if no value is provided. |
propertyHints | Record<string, ValueHints> | undefined |
A set of Value Hints of all properties. The key is the name of the property and the value a ValueHints object. Only applicable if the value is complex. |
ValueHintsOverride
ValueHintsOverride
has the same properties as ValueHints
, except that all of them are optional. This type is used for some RelationshipAttribute values
ValueHintsValue
Name | Type | Description |
---|---|---|
key | string | number | boolean |
The actual value. |
displayName | string |
How the value should be displayed on the UI. |
ThirdPartyRelationshipAttributeQuery
If you want to query Attributes the user has in the context of a Relationship with a third party, you can use the ThirdPartyRelationshipAttributeQuery
. An example would be the query for the number of a bonus card managed by another company (like Payback). A ThirdPartyRelationshipAttributeQuery has the following properties:
Name | Type | Description |
---|---|---|
@type | "ThirdPartyRelationshipAttributeQuery" |
|
validFrom | string | undefined |
The start date of the time frame the returned Attribute should be valid in. |
validTo | string | undefined |
The end date of the time frame the returned Attribute should be valid in. |
key | string |
The key of the RelationshipAttribute that should be queried. |
owner | string |
The owner of the queried RelationshipAttribute. Can be an empty string ("" ), if the owner is unknown or you are querying from multiple thirdParties that could own the attribute. |
thirdParty | string[] |
The Address of the third parties the RelationshipAttribute should be queried from. |
IQLQuery
If you want to query Attributes by their content, you can use the IQLQuery
.
It allows you to specify conditions the Attribute must match and which may be chained using binary operations.
Every property of the Attribute’s content may be queried, independend of whether it is nested or not, by formulating it as a lowercase key.
Furthermore, using an uppercase term is a shortcut for comparing the term to the value.@type
property and using #
refers to the tag
property.
For example, if you want to query a StreetAddress
in Germany which is tagged as [Primary Address]
the queryString
would be StreetAddress && value.country.value == Germany && #"Primary Address"
.
If no corresponding Attribute exists at the peer’s side, you are given the possibility to add attributeCreationHints
, suggesting to create an Attribute which matches a specific valueType
and optionally tags
.
Name | Type | Description |
---|---|---|
@type | "IQLQuery" |
|
queryString | string |
The condition the attribute must fulfill. It is made up of terms of the form <key> <operator> <value> , which may be chained using binary operations. Uppercase expressions refer to the property value@type and # to tags . |
attributeCreationHints | IQLQueryCreationHints | undefined |
Suggestions for creating a new Attribute, if the query returns empty. |
IQLQueryCreationHints
Name | Type | Description |
---|---|---|
valueType | AttributeValues.Identity.TypeName |
The value.@type of the Attribute, which should be created. |
tags | string[] | undefined |
The tags for the Attribute, which should be created. |
RelationshipTemplateContent
Theoretically you can send any kind of data in a RelationshipTemplate. However, if your peer uses the enmeshed App, it will only be able to process RelationshipTemplates that contain a RelationshipTemplateContent
, which looks like this:
Name | Type | Description |
---|---|---|
@type | "RelationshipTemplateContent" |
|
title | string | undefined |
An optional, human readable title that should be rendered in the UI. |
metadata | object | undefined |
Optional custom metadata that can be sent together with the RelationshipTemplate. This property is meant purely for developers who integrate with enmeshed. They can write for example some kind of key into this property, which can be used later to identify the content of this Template. |
onNewRelationship | Request |
The Request that should pop up to the user in case there is no Relationship yet. In this Request you can send Attributes of yourself the user needs to in order to know who’s Template it is (e.g. company name, address, …), as ask for Attributes of the user you need to know in the Relationship, or send some information you already know about the user, so it can be saved in its wallet (e.g. the customer id). |
onExistingRelationship | Request | undefined |
The Request that should pop up to the user in case a Relationship already exists. An example usage is a Request with an AuthenticationRequestItem for the sake of two-factor authentication. |
RelationshipCreationChangeRequestContent
The naming on this one in combination with its response
property is a bit confusing. Even though the RelationshipCreationChangeRequestContent
contains the word “Request”, it has a response
property.
This is because in the context of Relationships, there are RelationshipChanges, which have a request
and a response
property. But caution: these have nothing to do with the Content-types Request
and Response
.
Name | Type | Description |
---|---|---|
@type | "RelationshipCreationChangeRequestContent" |
|
response | Response |
The Response to the Request that was contained in the RelationshipTemplateContent (either in the onExistingRelationship property or in the onNewRelationship property). |
A Mail can be sent as the content of a Message. It is comparable with the classic email, so its properties should not contain any surprise.
Name | Type | Description |
---|---|---|
@type | "Mail" |
|
to | string[] |
The enmeshed Addresses of the main recipients of this Mail. |
cc | string[] | undefined |
The enmeshed Addresses that should receive a copy of this Mail, additionally to the ones specified in to . |
subject | string |
The subject of the Mail. |
body | string |
The body of the Mail. |
Consumption
DecideRequestItemParameters
In order to answer a Request, the Response must be formulated appropriately.
As an easier interface to do so various DecideRequestItemParameters
are provided.
If you want to reject any RequestItem, you must use the RejectRequestItemParameters
.
If you want to accept a RequestItem, however, depending on its kind you might need different parameters.
For example, an AuthenticationRequestItem can be accepted using the AcceptRequestItemParameters, but for a FreeTextRequestItem AcceptFreeTextRequestItemParameters
are required.
RejectRequestItemParameters
Name | Type | Description |
---|---|---|
accept | "false" |
The only possible value here is the string “false”. |
code | string | undefined |
A code telling the sender about the reason for the rejection. |
message | string | undefined |
A human readable message with details about the rejection. |
AcceptRequestItemParameters
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
AcceptDeleteAttributeRequestItemParameters
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
deletionDate | string |
The timestamp of when the Attribute will be deleted. Only dates in the future are allowed here. |
AcceptFreeTextRequestItemParameters
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
freeText | string |
The free text that is used to answer the RequestItem. |
AcceptProposeAttributeRequestItemParameters
The parameters to accept a ProposeAttributeRequestItem with an existing Attribute.
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
attributeId | string |
The id of the existing LocalAttribute. |
The parameters to accept a ProposeAttributeRequestItem with a new Attribute.
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
attribute | IdentityAttribute | RelationshipAttribute |
The new LocalAttribute. |
AcceptReadAttributeRequestItemParameters
The parameters to accept a ReadAttributeRequestItem with an existing Attribute.
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
existingAttributeId | string |
The id of the existing LocalAttribute. |
The parameters to accept a ReadAttributeRequestItem with a new Attribute.
Name | Type | Description |
---|---|---|
accept | "true" |
The only possible value here is the string “true”. |
newAttribute | IdentityAttribute | RelationshipAttribute |
The new LocalAttribute. |