docs: add example to exchange digital twins #313
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mgarciaLKS
requested changes
Aug 22, 2025
| > **Please** have a look at the `cURL explanation` Notes in the beginning of [Provide Digital Twins](provide-digitaltwins.md) to get more information about cURL. | ||
|
|
||
| This step continues the journey of our digital twin consumer Alice. After the digital twin provider Bob has successfully provided his digital twin via DTR and submodelserver in his EDC. Alice will now consume the digital twin. | ||
| We will use plain CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. |
There was a problem hiding this comment.
Suggested change
| We will use plain CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. | |
| We will use plain CLI tools (`curl`) for this, but feel free to use graphical tools such as Postman or Insomnia. |
|
|
||
| ### Authorization response | ||
|
|
||
|
|
| ### Authorization response | ||
|
|
||
|
|
||
| The response will contain the authorization details, including the `endpoint` and `authorization`which are needed to fetch the data via the data plane. |
There was a problem hiding this comment.
Suggested change
| The response will contain the authorization details, including the `endpoint` and `authorization`which are needed to fetch the data via the data plane. | |
| The response will contain the authorization details, including the `endpoint` and `authorization` which are needed to fetch the data via the data plane. |
| ## Step 5: Fetch data | ||
|
|
||
| Using the {{ENDPOINT}} and {{TOKEN}} from the response, Alice fetches the data. In our example the `uuid` `urn:uuid:b77c6d51-cd1f-4c9d-b5d4-091b22dd306b` for the data is already known. In | ||
| real life you would receive this information from the digital twin registry as an endpoint in the submodelDescriptors. |
There was a problem hiding this comment.
not necessary new line here
| We have already learned about the response of a catalog request in the [Provide Data](provide-data.md) guide. The response contains a list of assets that Alice can consume from Bob. | ||
|
|
||
| The response (here just an extract) will contain the `@id` `200` of the asset that Alice wants to consume, but also the `@id` `MjAw:MjAw:Y2ZjMzdlNmUtODAwNi00NGJjLWJhMWYtNjJkOWIzZWM0ZTQ3` of the offer | ||
| that Alice needs to reference in the negotiation. |
There was a problem hiding this comment.
not necessary new line here
| * **Submodel Server** - to create and provide data (so-called submodels) for digital twins based on aspect models | ||
| * **EDC** - to connect DTR and Submodel Server to your local dataspace. Both components, DTR and Submodel Server are only accessible via the EDC. | ||
|
|
||
|  |
There was a problem hiding this comment.
Would it be possible (if not much work) to modify the background color of Bobs and Alice actions, hard to read white text over it.
| ``` | ||
| ### Usage Policy for dDTR | ||
|
|
||
| The usage policy defines the conditions under which data from the decentralized Digital Twin Registry (dDTR) may be utilized. By using a standardized purpose such as **"cx.core.digitalTwinRegistry:1"**, it ensures that all providers within the Catena-X ecosystem employ a consistent usage policy. This enhances the transparency and trustworthiness of the system. |
There was a problem hiding this comment.
Suggested change
| The usage policy defines the conditions under which data from the decentralized Digital Twin Registry (dDTR) may be utilized. By using a standardized purpose such as **"cx.core.digitalTwinRegistry:1"**, it ensures that all providers within the Catena-X ecosystem employ a consistent usage policy. This enhances the transparency and trustworthiness of the system. | |
| The usage policy defines the conditions under which data from the decentralized Digital Twin Registry (dDTR) may be utilized. By using a standardized purpose, such as **"cx.core.digitalTwinRegistry:1"**, it ensures that all providers within the Catena-X ecosystem employ a consistent usage policy. This enhances the transparency and trustworthiness of the system. |
| ``` | ||
| ## Creating a dDTR Contract Definition | ||
|
|
||
| In common a contract definition always consists out of 1 to n assets, an access policy and 1 to n usage policies. So you should first create a access and usage policy for your registry (like shown above). In common policies can be reused, but please do not reuse the usage policy of the registry for other contract definitions as the purpose of the usage is focused on the dDTR use! |
There was a problem hiding this comment.
Suggested change
| In common a contract definition always consists out of 1 to n assets, an access policy and 1 to n usage policies. So you should first create a access and usage policy for your registry (like shown above). In common policies can be reused, but please do not reuse the usage policy of the registry for other contract definitions as the purpose of the usage is focused on the dDTR use! | |
| In common, a contract definition always consists out of 1 to n assets, an access policy and 1 to n usage policies. So you should first create an access and usage policy for your registry (like shown above). In common policies can be reused, but please do not reuse the usage policy of the registry for other contract definitions as the purpose of the usage is focused on the dDTR use! |
| ``` | ||
| ## Filter for the dDTR Offer | ||
|
|
||
| If everything is setup like described above, a data consumer should find the dDTR offer in the catalogue with the the catalogue request with the filter expression shown in the example. The filter uses the dct type to filter for the registry offer. |
There was a problem hiding this comment.
Suggested change
| If everything is setup like described above, a data consumer should find the dDTR offer in the catalogue with the the catalogue request with the filter expression shown in the example. The filter uses the dct type to filter for the registry offer. | |
| If everything is set up like described above, a data consumer should find the dDTR offer in the catalogue with the catalogue request with the filter expression shown in the example. The filter uses the dct type to filter for the registry offer. |
|
@th0masgl could you make the requested changes? |
Hi @mgarciaLKS , currently in parental leave, will find the time in mid of October... Perhaps @lgblaumeiser can help ? |
What do you say!!! That's great news, don't worry about this PR, I had no idea and besides, it's not a priority. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR extends the user guides with an example how to exchange digital twins between Alice & Bob.
Pre-review checks
Please ensure to do as many of the following checks as possible, before asking for committer review: