From 0e6837452a0fa790177f04347b1cc6178ff9cc17 Mon Sep 17 00:00:00 2001 From: Britta Stallknecht <146106656+britsta@users.noreply.github.com> Date: Thu, 5 Dec 2024 15:52:00 +0100 Subject: [PATCH] Format `address` as property of Identity (#285) * refactor: write consistently email instead of e-mail * feat: write address lowercase and format if possible * refactor: reformulate phrase "your address" * refactor: emphazise enmeshed Address as proper noun in some cases --- _docs_explore/23-privacy.md | 8 ++--- _docs_explore/60-addresses.md | 2 +- _docs_explore/63-blockchain.md | 2 +- _docs_integrate/attribute-values.md | 30 +++++++++---------- _docs_integrate/create-attributes-for-peer.md | 4 +-- _docs_integrate/data-model-overview.md | 14 ++++----- _docs_integrate/establish-relationships.md | 2 +- _docs_integrate/integration-example.md | 6 ++-- _docs_integrate/propose-attributes-to-peer.md | 4 +-- _docs_integrate/read-attributes-from-peer.md | 4 +-- .../request-and-response-introduction.md | 2 +- .../request-one-time-consent-of-peer.md | 4 +-- .../request-persistent-consent-of-peer.md | 4 +-- _docs_integrate/requests-via-messages.md | 8 ++--- _docs_integrate/share-attributes-with-peer.md | 20 ++++++------- .../update-attributes-by-succession.md | 4 +-- ...ase-consumption-accept-incoming-request.md | 2 +- ...eck-if-incoming-request-can-be-accepted.md | 2 +- ...onsumption-create-a-repositoryattribute.md | 3 +- ...sumption-create-a-shared-attribute-copy.md | 2 +- ...reate-and-share-a-relationshipattribute.md | 4 +-- ...e-consumption-get-own-shared-attributes.md | 2 +- ...-consumption-get-peer-shared-attributes.md | 2 +- ...er-about-repositoryattribute-succession.md | 4 +-- ...ase-consumption-query-incoming-requests.md | 2 +- ...ase-consumption-query-outgoing-requests.md | 2 +- ...consumption-share-a-repositoryattribute.md | 8 ++--- ...nsumption-succeed-a-repositoryattribute.md | 2 +- ...-device-get-profile-by-enmeshed-address.md | 4 +-- ...e-transport-get-relationship-by-address.md | 3 +- .../use-case-transport-query-files.md | 2 +- .../use-case-transport-query-messages.md | 6 ++-- .../use-case-transport-query-relationships.md | 2 +- ...e-transport-query-relationshiptemplates.md | 2 +- ...se-transport-query-tokens-by-parameters.md | 2 +- ...se-transport-send-message-to-recipients.md | 2 +- _includes/descr_createdBy | 2 +- ...06-30-announcing-enmeshed-v2-attributes.md | 2 +- 38 files changed, 89 insertions(+), 91 deletions(-) diff --git a/_docs_explore/23-privacy.md b/_docs_explore/23-privacy.md index 73b372185..014c93b37 100644 --- a/_docs_explore/23-privacy.md +++ b/_docs_explore/23-privacy.md @@ -30,7 +30,7 @@ Potential examples of personal data / PII: - Names - Addresses - Phone numbers -- E-Mail addresses +- Email addresses - Birth dates - Payment details - IP addresses @@ -61,7 +61,7 @@ Due to the broad scope of scenarios encompassed within the public sector, an abs The developers at enmeshed interpret the data privacy regulations narrowly, which has earned the appreciation of lawyers and data privacy experts for the design of the solution. Notably, the ability to delete all of the following data categories within our solution is pivotal for **absolute data privacy**: -1. (Non-technical) personal data which could directly identify a person (like names, e-mail addresses, birth dates, public/social ids, or phone numbers) is only processed in an end-to-end encrypted way between users and organizations. The central service does not have access to this data. +1. (Non-technical) personal data which could directly identify a person (like names, email addresses, birth dates, public/social ids, or phone numbers) is only processed in an end-to-end encrypted way between users and organizations. The central service does not have access to this data. 2. Pseudonyms or technical identifiers which are shared between multiple Identities (like enmeshed Addresses, enmeshed Public Keys, Device Ids, or Identity versions) are considered PII, as an entity could use this information to map this data to real world persons. 3. Pseudonyms, technical identifiers or secrets which are shared between two Identities (like Backbone credentials, device versions, or Relationship public keys) are considered PII, as an entity could use this information to map this data to real world persons. 4. One-way functions (hashes/digests) of PII are considered PII, as an entity theoretically has the possibility of mapping these hashes to real world persons or could potentially map the hashes to real world persons. @@ -72,7 +72,7 @@ When considering a **relative data privacy** , one might contend that only data ## Least Knowledge -'Least Knowledge' is the fundamental principle upon which enmeshed is built. As a result, the solution aims to minimize Personally Identifiable Information (PII) usage, thereby providing an optimal user experience and comprehensive features. In fact, the "usual personal data", like e-mail addresses, telephone numbers or names never reach the Backbone (and its operator) in cleartext. +'Least Knowledge' is the fundamental principle upon which enmeshed is built. As a result, the solution aims to minimize Personally Identifiable Information (PII) usage, thereby providing an optimal user experience and comprehensive features. In fact, the "usual personal data", like email addresses, telephone numbers or names never reach the Backbone (and its operator) in cleartext. - The enmeshed App stores the data in a local database on the device it is operating on. Data usually can only be sent to or received from the Backbone, generic Internet access from the App is blocked. - The enmeshed Connector stores the data in a local database within an organization's network. Data can only be sent to or received from the Backbone, no other Internet access should be made possible. @@ -94,7 +94,7 @@ enmeshed additionally follows the once-only principle for such data, thus enabli The Backbone is the most significant component in terms of privacy. As a centrally hosted component by a third party, it is understandable that privacy-related questions usually focus this component." -The Backbone only stores technical information of Identities or devices. It never has access to cleartext data such as content of Messages, names, e-mail addresses, and so on, as all this information is end-to-end encrypted. Furthermore, even encrypted data of the Backbone is not publicly available - only the Identities which have reason to access the data get access. +The Backbone only stores technical information of Identities or devices. It never has access to cleartext data such as content of Messages, names, email addresses, and so on, as all this information is end-to-end encrypted. Furthermore, even encrypted data of the Backbone is not publicly available - only the Identities which have reason to access the data get access. Without the actual keys from the respective Identities (which the Backbone hosting entity does not receive) the actual data cannot practically be decrypted or analyzed. The **relative data privacy** mindset should thus be reasonably fulfilled by using the enmeshed mechanisms. diff --git a/_docs_explore/60-addresses.md b/_docs_explore/60-addresses.md index d7fd11c04..a3d8a5f48 100644 --- a/_docs_explore/60-addresses.md +++ b/_docs_explore/60-addresses.md @@ -3,7 +3,7 @@ title: "enmeshed Addresses" permalink: /explore/addresses --- -The Address is the primary identifier for an enmeshed Identity. It is public and created out of the Identity’s Signature Public Key. Thus, the Identity’s root signature key and its corresponding Address are interlinked with each other and cannot be changed. Nobody is able to change the public key for a corresponding Address and everybody has the possibility to check, if a given public key matches a given Address without having to trust someone. Both are important security features. +The enmeshed Address is the primary identifier for an enmeshed Identity and stored within the `address` property of the data object of type [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). It is public and created out of the Identity’s Signature Public Key. Thus, the Identity’s root signature key and its corresponding Address are interlinked with each other and cannot be changed. Nobody is able to change the public key for a corresponding Address and everybody has the possibility to check, if a given public key matches a given Address without having to trust someone. Both are important security features. - As Addresses do not contain special characters, copy and pasting via double-click is supported. - As they do have a checksum included, syntactically wrong Addresses can be checked by a computer program locally. diff --git a/_docs_explore/63-blockchain.md b/_docs_explore/63-blockchain.md index c78b5dce3..4bed4a209 100644 --- a/_docs_explore/63-blockchain.md +++ b/_docs_explore/63-blockchain.md @@ -10,7 +10,7 @@ permalink: /explore/blockchain Having full control over data, authorizations, or the hard- and software one can use for using the data is called self-sovereignty. A self-sovereign Identity is a digital Identity which anybody can set up, without the power of somebody else to deny access, spy on or change the data. **Example:** -The common scenario in the Internet is, to create a user profile on a website, enter all the required information including username, password, e-mail address, and many more personal information. This data is stored on one central solution provider which has the complete authority over your account. This authority can be used for tracing or blocking users. A user would not be able to login or use all the features anymore - a common topic with social login providers. +The common scenario in the Internet is, to create a user profile on a website, enter all the required information including username, password, email address, and many more personal information. This data is stored on one central solution provider which has the complete authority over your account. This authority can be used for tracing or blocking users. A user would not be able to login or use all the features anymore - a common topic with social login providers. A self-sovereign Identity wouldn't work it that way: The user will always have the full control over this Identity – only the usage for a specific service (e.g. a specific social network) could be blocked by the network. But the Identity itself could still be used for any other tasks. diff --git a/_docs_integrate/attribute-values.md b/_docs_integrate/attribute-values.md index 73c580b51..36e344166 100644 --- a/_docs_integrate/attribute-values.md +++ b/_docs_integrate/attribute-values.md @@ -521,11 +521,11 @@ It is not recommended to send a DigitalIdentityDescriptor to another Identity by **Properties** -| Name | Type | Required | Validation | -| ------------ | ----------------------------- | :------: | ---------------------------------------------------- | -| `@type` | `"DigitalIdentityDescriptor"` | ✓ | | -| `address` | `string` | ✓ | The Address of the Identity that owns the statement. | -| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | +| Name | Type | Required | Validation | +| ------------ | ----------------------------- | :------: | -------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"DigitalIdentityDescriptor"` | ✓ | | +| `address` | `string` | ✓ | The `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that owns the statement. | +| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | ## StatementAuthorityType @@ -582,11 +582,11 @@ It is not recommended to send a object to another Identity by its own. Instead, **Properties** -| Name | Type | Required | Validation | -| ------------ | ------------------- | :------: | ---------------------------------------------------- | -| `@type` | `"StatementObject"` | ✓ | | -| `address` | `string` | ✓ | The Address of the Identity that owns the statement. | -| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | +| Name | Type | Required | Validation | +| ------------ | ------------------- | :------: | -------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"StatementObject"` | ✓ | | +| `address` | `string` | ✓ | The `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that owns the statement. | +| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | ## StatementPredicate @@ -611,11 +611,11 @@ It is not recommended to send a subject to another Identity by its own. Instead, **Properties** -| Name | Type | Required | Validation | -| ------------ | -------------------- | :------: | ---------------------------------------------------- | -| `@type` | `"StatementSubject"` | ✓ | | -| `address` | `string` | ✓ | The Address of the Identity that owns the statement. | -| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | +| Name | Type | Required | Validation | +| ------------ | -------------------- | :------: | -------------------------------------------------------------------------------------------------------------------- | +| `@type` | `"StatementSubject"` | ✓ | | +| `address` | `string` | ✓ | The `address` of the [Identity]({% link _docs_integrate/data-model-overview.md %}#identity) that owns the statement. | +| `attributes` | `string []` | ✗ | see [`Identity Attributes`](#identity-attributes) | ## Street diff --git a/_docs_integrate/create-attributes-for-peer.md b/_docs_integrate/create-attributes-for-peer.md index 8f135c3e4..ebca2c838 100644 --- a/_docs_integrate/create-attributes-for-peer.md +++ b/_docs_integrate/create-attributes-for-peer.md @@ -60,7 +60,7 @@ The following table provides an overview of the possible kinds of Attributes tha ### Example of creating an IdentityAttribute -We assume that the Integrator of the Sender wants to create an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) for the Recipient. To request the creation of this IdentityAttribute, the Sender needs to insert it into the `attribute` property of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. As the IdentityAttribute should be owned by the Recipient, an empty string is specified for its `owner` property. If the Sender sends the corresponding [Request via a Message]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-message), the Address of the Recipient could alternatively be specified explicitly. In our example, we have chosen to set the value of the `mustBeAccepted` property of the CreateAttributeRequestItem to `true`. Please note that the `<...>` notation is used as a placeholder for the actual data as usual. +We assume that the Integrator of the Sender wants to create an IdentityAttribute of type [EMailAddress]({% link _docs_integrate/attribute-values.md %}#emailaddress) for the Recipient. To request the creation of this IdentityAttribute, the Sender needs to insert it into the `attribute` property of the [CreateAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#createattributerequestitem) contained within the `items` property of the [Request]({% link _docs_integrate/data-model-overview.md %}#request) for creating Attributes. As the IdentityAttribute should be owned by the Recipient, an empty string is specified for its `owner` property. If the Sender sends the corresponding [Request via a Message]({% link _docs_integrate/create-attributes-for-peer.md %}#request-via-message), the address of the Recipient could alternatively be specified explicitly. In our example, we have chosen to set the value of the `mustBeAccepted` property of the CreateAttributeRequestItem to `true`. Please note that the `<...>` notation is used as a placeholder for the actual data as usual. ```jsonc { @@ -95,7 +95,7 @@ We now consider the case in which the Sender has an active [Relationship]({% lin "mustBeAccepted": true, "attribute": { "@type": "RelationshipAttribute", - "owner": "
", + "owner": "
", "key": "", "confidentiality": "public", "value": { diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 7f94036c8..3c07b22c0 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -93,7 +93,7 @@ A Relationship between two Identities is the prerequisite for them to exchange M | template | [`RelationshipTemplate`](#relationshiptemplate) | The RelationshipTemplate that was used to establish this Relationship. | | | status | `"Pending"` \| `"Active"` \| `"Rejected"` \| `"Revoked"` \| `"Terminated"` \| `"DeletionProposed"` | The status of this Relationship.
{::nomarkdown}
  • Pending: the Relationship was created, but not yet accepted by the recipient. In this state you cannot send Messages yet.
  • Active: this means that the Relationship is active. As long as it is active, both participants can exchange Messages.
  • Rejected: the Relationship was rejected by the recipient.
  • Revoked: the Relationship was revoked by the sender.
  • Terminated: No Messages can be sent. Either side can request reactivation from the peer.
  • Deletion Proposed: Your peer has decomposed the Relationship, i. e. locally deleted the Relationship and data transmitted during it.
{:/} | | | creationContent | [`RelationshipCreationContent`](#relationshipcreationcontent) \| [`ArbitraryRelationshipCreationContent`](#arbitraryrelationshipcreationcontent) | The content sent along when the Relationship is initiated. If the `template` contains a [RelationshipTemplateContent](#relationshiptemplatecontent), `RelationshipCreationContent` has to be used. Otherwise, an `ArbitraryRelationshipCreationContent` is used, which can be filled with anything. | will be encrypted before sent to the Backbone | -| peer | `string` | The Address of the Identity with which you have this Relationship. | saved only locally | +| peer | `string` | The `address` of the [Identity](#identity) with which you have this Relationship. | saved only locally | | auditLog | [`RelationshipAuditLogEntry`](#relationshipauditlogentry)`[]` | A log of Relationship operations like creating or accepting a pending Relationship. | | ### RelationshipAuditLogEntry @@ -103,7 +103,7 @@ The audit log records Relationship operations starting with the creation of the | Name | Type | Description | Remarks | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | createdAt | `string` | A timestamp that describes when the Relationship operation was executed. | | -| createdBy | `string` | The Address of the Identity that executed the Relationship operation. | | +| createdBy | `string` | The `address` of the [Identity](#identity) that executed the Relationship operation. | | | createdByDevice | `string` | The ID of the Device that executed the Relationship operation. You can use this information to track back who exactly did it. | | | reason | `"Creation"` \| `"AcceptanceOfCreation"` \| `"RejectionOfCreation"` \| `"RevocationOfCreation"` \| `"Termination"` \| `"ReactivationRequested"` \| `"AcceptanceOfReactivation"` \| `"RejectionOfReactivation"` \| `"RevocationOfReactivation"` \| `"Decomposition"` | The type of the Relationship operation.
{::nomarkdown}
  • Creation: creation of the pending Relationship.
  • AcceptanceOfCreation: acceptance of the pending Relationship.
  • RejectionOfCreation: rejection of the pending Relationship.
  • RevocationOfCreation: revocation of the pending Relationship.
  • Termination: termination of the active Relationship.
  • ReactivationRequested: request for the reactivation of the terminated Relationship.
  • AcceptanceOfReactivation: acceptance of the reactivation of the terminated Relationship.
  • RejectionOfReactivation: rejection of the reactivation of the terminated Relationship.
  • RevocationOfReactivation: revocation of the reactivation of the terminated Relationship.
  • Decomposition: decomposition of the terminated Relationship.
{:/} | | | oldStatus | `"Pending"` \| `"Active"` \| `"Terminated"` \| `undefined` | The status of the Relationship before the operation, it's `undefined` if the operation is the Relationship's creation. | | @@ -138,7 +138,7 @@ But if you are communicating with another Connector, you can use the [`Arbitrary | Name | Type | Description | Remarks | | ---------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | -| address | `string` | The Address of the recipient of the Message. | | +| 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 | | @@ -364,7 +364,7 @@ The LocalAttributeShareInfo helps to keep track of how the LocalAttribute was re | Name | Type | Description | | --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| peer | `string` | The Address of the Identity the LocalAttribute was received from/shared with. | +| peer | `string` | The `address` of the [Identity](#identity) the LocalAttribute was received from/shared with. | | requestReference | `string` \| `undefined` | The `id` of the [LocalRequest](#localrequest) the LocalAttribute was received in/sent with. If this is set, `notificationReference` must be undefined. | | notificationReference | `string` \| `undefined` | The `id` of the [LocalNotification](#localnotification) the LocalAttribute was received in/sent with. If this is set, `requestReference` must be undefined. | | sourceAttribute | `string` \| `undefined` | If the [LocalAttribute](#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 Identity who is in the Relationship the source RelationshipAttribute is copied from and who emitted the ThirdPartyRelationshipAttribute to the peer. | @@ -397,7 +397,7 @@ A LocalAttributeListener is created when you accept an incoming Request with a [ | ----- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | `string` | {% include descr_id class="LocalAttributeListener" prefix="ATL" %} | | query | [`IdentityAttributeQuery`](#identityattributequery) \| [`ThirdPartyRelationshipAttributeQuery`](#thirdpartyrelationshipattributequery) | The query the Attribute that is listened to must match. Note that you cannot send a [`RelationshipAttributeQuery`](#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. | +| peer | `string` | The address of the peer that requested the Attribute Listener. | # Content Types @@ -942,8 +942,8 @@ A Mail can be sent as the content of a [Message](#message). It is comparable wit | 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`. | +| 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. | diff --git a/_docs_integrate/establish-relationships.md b/_docs_integrate/establish-relationships.md index 5f1718b46..e9f8dd5d9 100644 --- a/_docs_integrate/establish-relationships.md +++ b/_docs_integrate/establish-relationships.md @@ -93,7 +93,7 @@ Only that Identity will be able to continue with establishing a Relationship. Th ### Successfully Created RelationshipTemplate -If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the Address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context. +If you have successfully created the [RelationshipTemplate]({% link _docs_integrate/data-model-overview.md %}#relationshiptemplate) on the templator, you will receive a success response from which you can read its `id`. As the templator is the creator of the RelationshipTemplate, the `createdBy` property contains the address of the templator. For this reason, the value of the `isOwn` property is set to `true` in this context. {% include copy-notice description="Save the `id` of the RelationshipTemplate so that you can refer to it and make it available to other Identities later. For the same reason, save the value of the property `truncatedReference`." %} diff --git a/_docs_integrate/integration-example.md b/_docs_integrate/integration-example.md index 980c293e8..32eb2d389 100644 --- a/_docs_integrate/integration-example.md +++ b/_docs_integrate/integration-example.md @@ -88,7 +88,7 @@ The content of the RelationshipTemplate can be widely configured, but for simpli On the one hand, we want to [share an Attribute]({% link _docs_integrate/share-attributes-with-peer.md %}) with the App, namely the display name of our Connector we created in the previous step. For this, we use a [ShareAttributeRequestItem]({% link _docs_integrate/data-model-overview.md %}#shareattributerequestitem). On the other hand, we use [ReadAttributeRequestItems]({% link _docs_integrate/data-model-overview.md %}#readattributerequestitem) to [receive Attributes]({% link _docs_integrate/read-attributes-from-peer.md %}) from the App. -Let's assume the Connector needs to know the given name and surname of its contact to create a Relationship and, additionally, offers the option to specify an e-mail address for communication. +Let's assume the Connector needs to know the given name and surname of its contact to create a Relationship and, additionally, offers the option to specify an email address for communication. ```json { @@ -228,7 +228,7 @@ Example: {% include rapidoc api_route_regex="^put /api/v2/Relationships/{id}/Accept$" %} Now the Relationship is in the `Active` state, so we can start to communicate with the opposite Identity, which we will do in the next part of this tutorial. -For this, we will need the address of that Identity. +For this, we will need the `address` of that [Identity]({% link _docs_integrate/data-model-overview.md %}#identity). It can be found in the Response, when accepting the Relationship. {% include copy-notice description="Save the `peer` property of the Response (`did:e:_________________`). You will need it in the next step." %} @@ -237,7 +237,7 @@ It can be found in the Response, when accepting the Relationship. After having established a Relationship with an Identity, we can start to exchange [Messages]({% link _docs_integrate/data-model-overview.md %}#message). enmeshed defines different types of Messages. -In this tutorial we will focus on Messages of type [Mail]({% link _docs_integrate/data-model-overview.md %}#mail), which can be compared to a classic e-mail: it is possible to specify one or more recipients, a subject and a body, as well as to add attachments. +In this tutorial we will focus on Messages of type [Mail]({% link _docs_integrate/data-model-overview.md %}#mail), which can be compared to a classic email: it is possible to specify one or more recipients, a subject and a body, as well as to add attachments. ### Sending a Message with a Connector diff --git a/_docs_integrate/propose-attributes-to-peer.md b/_docs_integrate/propose-attributes-to-peer.md index 915aefa81..2015182e3 100644 --- a/_docs_integrate/propose-attributes-to-peer.md +++ b/_docs_integrate/propose-attributes-to-peer.md @@ -258,7 +258,7 @@ We assume that the Recipient confirms the fittingness of the PersonName proposed "accept": true, "attribute": { "@type": "IdentityAttribute", - "owner": "
", + "owner": "
", "value": { "@type": "PersonName", "givenName": "", @@ -273,7 +273,7 @@ We assume that the Recipient confirms the fittingness of the PersonName proposed "accept": true, "attribute": { "@type": "IdentityAttribute", - "owner": "
", + "owner": "
", "value": { "@type": "EMailAddress", "value": "" diff --git a/_docs_integrate/read-attributes-from-peer.md b/_docs_integrate/read-attributes-from-peer.md index 4dc4e33ea..395c77ce7 100644 --- a/_docs_integrate/read-attributes-from-peer.md +++ b/_docs_integrate/read-attributes-from-peer.md @@ -46,7 +46,7 @@ For reading a single Attribute, the Sender needs to insert a single RequestItem The Sender can use a ReadAttributeRequestItem to create a RelationshipAttribute in the context of a Relationship between itself and the Recipient if it wants the [RelationshipAttributeValue]({% link _docs_integrate/attribute-values.md %}#relationship-attributes) to be set by the Recipient. Even if it seems misleading to use a ReadAttributeRequestItem to create a RelationshipAttribute, this terminology makes sense insofar as the RelationshipAttributeValue should be read from the Recipient in order to be able to create it. {: .notice--info} -Note that the Sender cannot explicitly specify the Recipient's Address as the value for the `owner` property of the RelationshipAttributeQuery because the Address does not have to be known beforehand. This is the case if the [Request is sent via a RelationshipTemplate]({% link _docs_integrate/read-attributes-from-peer.md %}#request-via-relationshiptemplate) and not via a Message. Therefore, an empty string must be specified as the `owner` instead if the Sender wants the RelationshipAttribute to be owned by the Recipient. If the Sender is interested in a RelationshipAttribute that the Recipient has in the context of a Relationship with a third party, a [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) can be used. In addition, it is also permitted to specify an [IQLQuery]({% link _docs_integrate/data-model-overview.md %}#iqlquery) for the `query` property of the ReadAttributeRequestItem. +Note that the Sender cannot explicitly specify the Recipient's address as the value for the `owner` property of the RelationshipAttributeQuery because the address does not have to be known beforehand. This is the case if the [Request is sent via a RelationshipTemplate]({% link _docs_integrate/read-attributes-from-peer.md %}#request-via-relationshiptemplate) and not via a Message. Therefore, an empty string must be specified as the `owner` instead if the Sender wants the RelationshipAttribute to be owned by the Recipient. If the Sender is interested in a RelationshipAttribute that the Recipient has in the context of a Relationship with a third party, a [ThirdPartyRelationshipAttributeQuery]({% link _docs_integrate/data-model-overview.md %}#thirdpartyrelationshipattributequery) can be used. In addition, it is also permitted to specify an [IQLQuery]({% link _docs_integrate/data-model-overview.md %}#iqlquery) for the `query` property of the ReadAttributeRequestItem. ### Combinations and usage scenarios of ReadAttributeRequestItem @@ -125,7 +125,7 @@ If the Sender has established an active Relationship with the Recipient and the "@type": "ThirdPartyRelationshipAttributeQuery", "key": "", "owner": "recipient", - "thirdParty": ["
"] + "thirdParty": ["
"] } } ] diff --git a/_docs_integrate/request-and-response-introduction.md b/_docs_integrate/request-and-response-introduction.md index a0e07f349..66220fb04 100644 --- a/_docs_integrate/request-and-response-introduction.md +++ b/_docs_integrate/request-and-response-introduction.md @@ -440,7 +440,7 @@ For this, they provide a QR code, linking to a RelationshipTemplate. In its `content.onNewRelationship` property it holds a Request with two RequestItemGroups. One of them contains Attributes the company shares with the peer, e.g. the company name. The other contains Attributes it would like to query from the peer. -In this example they are the given and surname and optionally an e-mail address, following the [Integration example]({% link _docs_integrate/integration-example.md %}). +In this example they are the given and surname and optionally an email address, following the [Integration example]({% link _docs_integrate/integration-example.md %}). Now, an interested person can scan the QR code, provide their information and send their Response inside a Relationship's creation content. Once the company accepts the new Relationship, they can exchange Messages or other data using enmeshed. diff --git a/_docs_integrate/request-one-time-consent-of-peer.md b/_docs_integrate/request-one-time-consent-of-peer.md index a9beb56f5..dae8497ee 100644 --- a/_docs_integrate/request-one-time-consent-of-peer.md +++ b/_docs_integrate/request-one-time-consent-of-peer.md @@ -79,7 +79,7 @@ Please note that the `<...>` notation is used as a placeholder for the actual da } ] }, - "peer": "
" + "peer": "
" } ``` @@ -92,7 +92,7 @@ After the Request has been created, the Sender can send it to the Recipient. To ```jsonc { - "recipients": ["
"], + "recipients": ["
"], "content": { "@type": "Request", "id": "", diff --git a/_docs_integrate/request-persistent-consent-of-peer.md b/_docs_integrate/request-persistent-consent-of-peer.md index f0c3ce628..43bbcd82d 100644 --- a/_docs_integrate/request-persistent-consent-of-peer.md +++ b/_docs_integrate/request-persistent-consent-of-peer.md @@ -79,7 +79,7 @@ As already indicated, the Request contains a [CreateAttributeRequestItem]({% lin } ] }, - "peer": "
" + "peer": "
" } ``` @@ -92,7 +92,7 @@ After the Request has been created, the Sender can send it to the Recipient. To ```jsonc { - "recipients": ["
"], + "recipients": ["
"], "content": { "@type": "Request", "id": "", diff --git a/_docs_integrate/requests-via-messages.md b/_docs_integrate/requests-via-messages.md index 72408c57a..8d4e3d892 100644 --- a/_docs_integrate/requests-via-messages.md +++ b/_docs_integrate/requests-via-messages.md @@ -35,7 +35,7 @@ We'll go through the steps of validating and creating the Request, sending and r This guide assumes that you already have an active [Relationship]({% link _docs_integrate/data-model-overview.md %}#relationship) between the two Connectors, e.g. from following the [Integration Example]({% link _docs_integrate/integration-example.md %}) or the scenario page [Requests via RelationshipTemplates]({% link _docs_integrate/requests-via-relationshiptemplates.md %}). If that is not the case, either take a look at those guides first or follow the instructions of how to [establish a Relationship]({% link _docs_integrate/establish-relationships.md %}) to another Identity. -In order to send a Message to the Recipient, it is required to know their enmeshed Address. +In order to send a Message to the Recipient, it is required to know their enmeshed address. To retrieve it, the Sender can [query their Relationships]({% link _docs_use-cases/use-case-transport-query-relationships.md %}) and look for the right one. ```jsonc @@ -73,7 +73,7 @@ If you are sending a Request via Message, you'll always know the peer, as it is } ] }, - "peer": "
" + "peer": "
" } ``` @@ -91,7 +91,7 @@ Also, note that the `content` was extented by the `@type` property and a generat { "id": "REQ...", "isOwn": true, - "peer": "
", + "peer": "
", "createdAt": "