diff --git a/_docs_integrate/attribute-introduction.md b/_docs_integrate/attribute-introduction.md index f6dbd99b0..63a2c6e88 100644 --- a/_docs_integrate/attribute-introduction.md +++ b/_docs_integrate/attribute-introduction.md @@ -32,7 +32,10 @@ This guide provides an introduction to [Attributes]({% link _docs_integrate/data ### IdentityAttribute value types -The [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes) are used to define the type of the `value` property of an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). In order to fulfill various purposes, many such IdentityAttribute value types are provided. If the IdentityAttribute value type used is not sufficient to clearly characterize the IdentityAttribute, `tags` can be used for a more precise description of its meaning. +The [IdentityAttribute value types]({% link _docs_integrate/attribute-values.md %}#identity-attributes) are used to define the type of the `value` property of an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute). +In order to fulfill various purposes, many such IdentityAttribute value types are provided. +If the IdentityAttribute value type used is not sufficient to clearly characterize the IdentityAttribute, `tags` can be used for a more precise description of its meaning. +Apart from custom `tags`, which must have the prefix `x+%+` or `X+%+`, only Backbone-defined `tags` may be used, which can be queried using the [Get AttributeTagCollection]({% link _docs_use-cases/use-case-consumption-get-attributetagcollection.md %}) use case. The storage of multiple IdentityAttributes of the same value type is possible. If an Identity receives a [Request for an IdentityAttribute of a certain value type]({% link _docs_integrate/read-attributes-from-peer.md %}#example-of-reading-an-identityattribute), it can choose which of the matching IdentityAttributes it wants to provide for its [Response]({% link _docs_integrate/data-model-overview.md %}#response) to the [Request]({% link _docs_integrate/data-model-overview.md %}#request). For example, storing multiple IdentityAttributes of the same value type is beneficial if an Identity has more than one residential address. Using `tags` helps to distinguish such IdentityAttributes from each other. {: .notice--info} diff --git a/_docs_integrate/data-model-overview.md b/_docs_integrate/data-model-overview.md index 1ae20c855..383883a21 100644 --- a/_docs_integrate/data-model-overview.md +++ b/_docs_integrate/data-model-overview.md @@ -176,21 +176,21 @@ Its metadata information is stored in a data object of type File. A File further has its content, of course. But since this is not a JSON property, it is not included in the following table. The content of the File can be downloaded separately by executing the [Download File]({% link _docs_use-cases/use-case-transport-download-file.md %}) use case. -| Name | Type | Description | Remarks | -| ------------------ | ------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -| id | `string` | {% include descr_id class="File" prefix="FIL" %} | | -| createdAt | `string` | {% include descr_createdAt class="File" %} | | -| createdBy | `string` | {% include descr_createdBy class="File" %} | | -| createdByDevice | `string` | {% include descr_createdByDevice class="File" %} | | -| expiresAt | `string` | {% include descr_expiresAt class="File" %} | | -| 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 | -| tags | `string[]` \| `undefined` | To specify additional information. | will be encrypted before sent to the Backbone | -| mimetype | `string` | The [mimetype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the file. | will be encrypted before sent to the Backbone | -| title | `string` \| `undefined` | 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 | -| isOwn | `boolean` | {% include descr_isOwn class="File" %} | saved only locally | -| truncatedReference | `string` | {% include descr_truncatedReference class="File" %} | saved only locally | +| Name | Type | Description | Remarks | +| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| id | `string` | {% include descr_id class="File" prefix="FIL" %} | | +| createdAt | `string` | {% include descr_createdAt class="File" %} | | +| createdBy | `string` | {% include descr_createdBy class="File" %} | | +| createdByDevice | `string` | {% include descr_createdByDevice class="File" %} | | +| expiresAt | `string` | {% include descr_expiresAt class="File" %} | | +| 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 | +| tags | `string[]` \| `undefined` | To specify additional information. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) for the [IdentityAttribute](#identityattribute) `value.@type` [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) or if it starts with the custom tag prefix `x+%+` or `X+%+`. This validation is needed as an associated IdentityAttribute with IdentityFileReference as `value.@type` will have these `tags` as well if it is created for the File during [transferring its ownership to a peer]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer). | will be encrypted before sent to the Backbone | +| mimetype | `string` | The [mimetype](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) of the file. | will be encrypted before sent to the Backbone | +| title | `string` \| `undefined` | 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 | +| isOwn | `boolean` | {% include descr_isOwn class="File" %} | saved only locally | +| truncatedReference | `string` | {% include descr_truncatedReference class="File" %} | saved only locally | ## Identity @@ -434,7 +434,7 @@ A LocalAttributeListener is created when you accept an incoming Request with a [ The AttributeTagCollection is defined by the Backbone and specifies which `tags` are allowed for which [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `value.@type`. It can be queried from the Backbone by using the [Get AttributeTagCollection]({% link _docs_use-cases/use-case-consumption-get-attributetagcollection.md %}) use case. -Apart from the Backbone-defined `tags`, only `tags` starting with the custom tag prefix `x+%+` or `X+%+` will be allowed to use when working with IdentityAttributes. +Apart from the Backbone-defined `tags`, only `tags` starting with the custom tag prefix `x+%+` or `X+%+` are allowed to use when working with IdentityAttributes. | Name | Type | Description | | -------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -922,12 +922,12 @@ An Attribute is some piece of information about an Identity itself (e.g. its nam IdentityAttributes describe an Identity itself. Their values are strongly normalized. There is a list of available values [here]({% link _docs_integrate/attribute-values.md %}). -| 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. | -| value | [`IdentityAttributeValue`]({% link _docs_integrate/attribute-values.md %}#identity-attributes) | The Attribute's value. | -| tags | `string[]` \| `undefined` | To specify additional information. | +| 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. | +| value | [`IdentityAttributeValue`]({% link _docs_integrate/attribute-values.md %}#identity-attributes) | The Attribute's value. | +| tags | `string[]` \| `undefined` | To specify additional information. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) or if it starts with the custom tag prefix `x+%+` or `X+%+`. | ### RelationshipAttribute @@ -950,11 +950,11 @@ One of the main features of enmeshed is sharing Attributes. For this, an Identit An `IdentityAttributeQuery` is used to query for IdentityAttributes. For that, it defines the following properties: -| Name | Type | Description | -| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- | -| @type | `"IdentityAttributeQuery"` | | -| valueType | `string` | The type of value that should be queried, e.g. `"StreetAddress"`, `"BirthDate"` or `"Nationality"`. | -| tags | `string[]` \| `undefined` | To specify additional information. | +| Name | Type | Description | +| --------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| @type | `"IdentityAttributeQuery"` | | +| valueType | `string` | The type of value that should be queried, e.g. `"StreetAddress"`, `"BirthDate"` or `"Nationality"`. | +| tags | `string[]` \| `undefined` | To specify additional information. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) or if it starts with the custom tag prefix `x+%+` or `X+%+`. | You can only query IdentityAttributes owned by the recipient of the query. @@ -1026,10 +1026,10 @@ If you want to query IdentityAttributes by their content, you can use the `IQLQu #### IQLQueryCreationHints -| Name | Type | Description | -| --------- | ----------------------------------- | -------------------------------------------------------------------- | -| valueType | `AttributeValues.Identity.TypeName` | The `value.@type` of the IdentityAttribute, which should be created. | -| tags | `string[]` \| `undefined` | The `tags` for the IdentityAttribute, which should be created. | +| Name | Type | Description | +| --------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| valueType | `AttributeValues.Identity.TypeName` | The `value.@type` of the IdentityAttribute, which should be created. | +| tags | `string[]` \| `undefined` | The `tags` for the IdentityAttribute, which should be created. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) or if it starts with the custom tag prefix `x+%+` or `X+%+`. | ## RelationshipTemplateContent @@ -1153,11 +1153,11 @@ The parameters to accept a ProposeAttributeRequestItem with a new Attribute. 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. | -| tags | `string[]` \| `undefined` | If additional `tags` are requested, that the exsiting Attibute doesn't have, yet, they can be specified using this property. | +| Name | Type | Description | +| ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| accept | `"true"` | The only possible value here is the string "true". | +| existingAttributeId | `string` | The `id` of the existing LocalAttribute. | +| tags | `string[]` \| `undefined` | If additional `tags` are requested, that the exsiting Attibute doesn't have, yet, they can be specified using this property. A tag is valid if it is contained in the [AttributeTagCollection](#attributetagcollection) or if it starts with the custom tag prefix `x+%+` or `X+%+`. | The parameters to accept a ReadAttributeRequestItem with a new Attribute. diff --git a/_docs_integrate/error-codes.md b/_docs_integrate/error-codes.md index 849f23b1e..84122b29f 100644 --- a/_docs_integrate/error-codes.md +++ b/_docs_integrate/error-codes.md @@ -42,6 +42,7 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.consumption.attributes.invalidDeletionInfoOfPeerSharedAttribute" %} | The only valid values of the property [`deletionStatus` for peer shared Attributes]({% link _docs_integrate/delete-attributes.md %}#delete-peer-shared-attributes) are `"DeletedByOwner"` or `"ToBeDeleted"`. | | {% include anchor a="error.consumption.attributes.
invalidDeletionInfoOfThirdPartyRelationshipAttribute" %} | The only valid `deletionStatus` for [ThirdPartyRelationshipAttributes]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) is `"DeletedByPeer"`, see ['Delete a ThirdPartyRelationshipAttribute']({% link _docs_use-cases/use-case-consumption-delete-a-thirdpartyrelationshipattribute-and-notify-peer.md %}) for more details. | | {% include anchor a="error.consumption.attributes.invalidParentSuccessor" %} | The [complex parent successor of this Attribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-a-repositoryattribute) does not exist. | +| {% include anchor a="error.consumption.attributes.invalidTags" %} | Some of the provided [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) `tags` are invalid. | | {% include anchor a="error.consumption.attributes.isNotOwnSharedAttribute" %} | The Attribute is not an [own shared Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | | {% include anchor a="error.consumption.attributes.isNotPeerSharedAttribute" %} | The Attribute is not a [peer shared Attribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | | {% include anchor a="error.consumption.attributes.isNotRepositoryAttribute" %} | The given Attribute is not a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute). | @@ -60,7 +61,7 @@ Please find a list of enmeshed error codes below. Most often the errors occur on | {% include anchor a="error.consumption.attributes.setPredecessorIdDoesNotMatchActualPredecessorId" %} | The predecessor's `id` and the explicitly set value for the successor's `succeeds` field don't match. | | {% include anchor a="error.consumption.attributes.setDefaultRepositoryAttributesIsDisabled" %} | Setting default RepositoryAttributes is disabled for this Account. | | {% include anchor a="error.consumption.attributes.successionMustChangeContent" %} | An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must change the Attribute's `content`. | -| {% include anchor a="error.consumption.attributes.successionMustNotChangeContentType" %} | The successor Attribute's `content` type does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `content` type, i.e. an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) must not be succeeded by a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) and v.v. | +| {% include anchor a="error.consumption.attributes.successionMustNotChangeContentType" %} | The successor Attribute's `content` type does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `content` type, i.e. an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) must not be succeeded by a [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute) and v.v. | | {% include anchor a="error.consumption.attributes.successionMustNotChangeKey" %} | The predecessor [RelationshipAttribute]({% link _docs_integrate/data-model-overview.md %}#relationshipattribute)'s `key` does not match that of the successor. The [succession of a RelationshipAttribute]({% link _docs_integrate/update-attributes-by-succession.md %}#succeeding-a-relationshipattribute-and-notifying-the-peer) must not change the `key`. | | {% include anchor a="error.consumption.attributes.successionPeerIsNotOwner" %} | The peer of the succeeded Attribute is not its `owner`. This may be an attempt of spoofing. | | {% include anchor a="error.consumption.attributes.successionMustNotChangeOwner" %} | The successor Attribute's `owner` does not match that of the predecessor. An [Attribute succession]({% link _docs_integrate/update-attributes-by-succession.md %}) must not change the Attribute's `owner`. | diff --git a/_docs_integrate/exchange-files-using-attributes.md b/_docs_integrate/exchange-files-using-attributes.md index 424fe4152..7be049974 100644 --- a/_docs_integrate/exchange-files-using-attributes.md +++ b/_docs_integrate/exchange-files-using-attributes.md @@ -205,6 +205,7 @@ If the recipient agrees to receive the ownership of one of the sender's Files, t The [AcceptRequestItemParameters]({% link _docs_integrate/data-model-overview.md %}#acceptrequestitemparameters) must be used for this. The acceptance of a TransferFileOwnershipRequestItem leads to the transfer of the ownership of the File on the Backbone. Additionally, a [RepositoryAttribute]({% link _docs_integrate/data-model-overview.md %}#localattribute) will be created for the recipient, whose `content` is an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type`. +If the File has `tags`, the IdentityAttribute will have the same `tags`. The `value` of the IdentityFileReference is the `truncatedReference` of the File that is now owned by the recipient. Also, the newly created RepositoryAttribute of the recipient will be shared with the sender, i.e. an own shared IdentityAttribute will be created for the recipient. Based on this, an appropriate AcceptResponseItem of type [TransferFileOwnershipAcceptResponseItem]({% link _docs_integrate/data-model-overview.md %}#transferfileownershipacceptresponseitem) is generated. diff --git a/_docs_use-cases/use-case-transport-upload-own-file.md b/_docs_use-cases/use-case-transport-upload-own-file.md index 9cd30a9f1..4ed020600 100644 --- a/_docs_use-cases/use-case-transport-upload-own-file.md +++ b/_docs_use-cases/use-case-transport-upload-own-file.md @@ -55,7 +55,7 @@ In the latter case, the [Token for the File must be created]({% link _docs_use-c - Optionally, `expiresAt` can be specified, which describes the ISODateTime the File expires. - Optionally, a `title` can be provided for the File. - Optionally, a `description` can be provided for the File. -- Optionally, `tags` can be provided for the File. +- Optionally, `tags` can be provided for the File. If an [IdentityAttribute]({% link _docs_integrate/data-model-overview.md %}#identityattribute) with [IdentityFileReference]({% link _docs_integrate/attribute-values.md %}#identityfilereference) as `value.@type` is created for the File during [transferring the ownership of the File to a peer]({% link _docs_integrate/exchange-files-using-attributes.md %}#transfer-the-ownership-of-a-file-to-a-peer), it will have these `tags` as well. For this reason, a tag is valid if it is contained in the [AttributeTagCollection]({% link _docs_integrate/data-model-overview.md %}#attributetagcollection) for the `value.@type` IdentityFileReference or if it starts with the custom tag prefix `x+%+` or `X+%+`. ## On Success