Merge pull request #654 from arnoweiss/docs/dt/prep-24-03

docs(dt): prepare for R24-03
eclipse-tractusx · Mar 7, 2024 · f703119 · f703119
2 parents 2d24d22 + 13e24b3
commit f703119
Show file tree

Hide file tree

Showing 9 changed files with 586 additions and 198 deletions.
diff --git a/...ts/kits/Digital Twin Kit/Software Development View/page_interaction-patterns.md b/...ts/kits/Digital Twin Kit/Software Development View/page_interaction-patterns.md
diff --git a/...ts/Digital Twin Kit/Software Development View/page_software-development-view.md b/...ts/Digital Twin Kit/Software Development View/page_software-development-view.md
diff --git a/docs-kits/kits/Digital Twin Kit/assets/img/DTKIT_discovery_seq.svg b/docs-kits/kits/Digital Twin Kit/assets/img/DTKIT_discovery_seq.svg
diff --git a/docs-kits/kits/Digital Twin Kit/assets/img/DTKIT_terminology.svg b/docs-kits/kits/Digital Twin Kit/assets/img/DTKIT_terminology.svg
diff --git a/docs-kits/kits/Digital Twin Kit/page_adoption-view.md b/docs-kits/kits/Digital Twin Kit/page_adoption-view.md
@@ -18,11 +18,11 @@ Adoption View of the Kit.
 
 ### Vision
 
-The aim of the Digital Twin Kit is to trace parts and materials across the entire value chain to enable data driven use 
-cases over all n-tier levels without compromising data sovereignty. This Kit enables data and app providers to deliver 
+The aim of the Digital Twin Kit is to trace parts and materials across the entire value chain to enable data driven use
+cases over all n-tier levels without compromising data sovereignty. This Kit enables data and app providers to deliver
 solutions for building data chains and to send quality notifications on all levels and industries.
 
-The Kits purpose is to provide the Catena-X Automotive Network with a uniform infrastructure to enable data-level 
+The Kits purpose is to provide the Catena-X Automotive Network with a uniform infrastructure to enable data-level
 interoperability between Business Partners. Regardless of the data's provenance, the Kit sets the scene
 for a comprehensive landscape of distributed Digital Twins of assets (mostly parts) along the entire lifecycle of the
 supply chain.
@@ -37,21 +37,21 @@ back to the public. A priority is the seamless integration with other Catena-X d
 
 ### Customer Journey
 
-With the Digital Twin Kit, all roles mentioned in the [Operating Model Whitepaper](https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Model_Whitepaper_02_12_22.pdf) 
+With the Digital Twin Kit, all roles mentioned in the [Operating Model Whitepaper](https://catena-x.net/fileadmin/user_upload/Publikationen_und_WhitePaper_des_Vereins/CX_Operating_Modelv2.1_final.pdf)
 are given the necessary tooling to format their data and APIs in a standardized manner.
 
 <!-- !Mandatory! -->
-## Business Value
+## Business Value & Business Processes
 
-Point-to-Point integration between Business Partners is challenging. On the one hand, all questions of sovereignty, 
-authorization, authentication must be agreed upon and implemented. In the Catena-X network, that is covered by the 
-[Connector Kit](https://eclipse-tractusx.github.io/docs-kits/category/connector-kit) and the services it relies on. 
+Point-to-Point integration between Business Partners is challenging. On the one hand, all questions of sovereignty,
+authorization, authentication must be agreed upon and implemented. In the Catena-X network, that is covered by the
+[Connector Kit](https://eclipse-tractusx.github.io/docs-kits/category/connector-kit) and the services it relies on.
 
-What this Kit adds is a set of technologies to reduce the integration efforts on the data level. Data Consumers can 
+What this Kit adds is a set of technologies to reduce the integration efforts on the data level. Data Consumers can
 develop their applications against data formats and interfaces that are standardized encouraging client-side reuse.
-Consequently, data providers present data agnostic to who will consume the data from. This reduces the investment necessary 
-to onboard to additional Catena-X use-cases significantly.  Consuming applications can be substituted seamlessly as 
-they are developed against the relevant Catena-X standards - further lowering the bar of entry for new applications in 
+Consequently, data providers present data agnostic to who will consume the data from. This reduces the investment necessary
+to onboard to additional Catena-X use-cases significantly.  Consuming applications can be substituted seamlessly as
+they are developed against the relevant Catena-X standards - further lowering the bar of entry for new applications in
 the ecosystem.
 
 <!-- !Mandatory! -->
@@ -68,13 +68,13 @@ expands with the scope of the model.
 - A distributed infrastructure of central and decentral components integrating hand-in-hand with backend-systems southward
 and the network northward.
 
-- Extensive meta-model to create a virtual representation of asses across their entire lifecycle.
+- Extensive meta-model to create a virtual representation of assets across their entire lifecycle.
 
 ### Example
 
-The [Traceability Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Adoption%20View%20Traceability%20Kit#logic--schema) 
-and the [Data Chain Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Documentation/irs_arc42) 
-build on Digital Twins and leverage many of this Kit's content. The Data Chain Kit would be unimagineable without the 
+The [Traceability Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Traceability%20Kit/Adoption%20View%20Traceability%20Kit#logic--schema)
+and the [Data Chain Kit](https://eclipse-tractusx.github.io/docs-kits/kits/Data%20Chain%20Kit/Documentation/irs_arc42)
+build on Digital Twins and leverage many of this Kit's content. The Data Chain Kit would be unimagineable without the
 pre-defined endpoint- and payload-definition that is the Digital Twin Kit. Likewise,
 coupling the chains' elements would be impossible without a unified hierarchical structure running with all participants.
 For more info how specifically the Asset Administration Shell is used, consult the Kits.
@@ -83,12 +83,19 @@ For more info how specifically the Asset Administration Shell is used, consult t
 
 ### CX-Standards
 
-- [CX - 0001 EDC Discovery API](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_PDF_Maerz/9_Data-Discovery-Services/CX_-_0001_EDC_DISCOVERY_API_PlatformCapabilityDS_v_1.0.1-1.pdf) 
-- [CX - 0002 Digital Twins in Catena-X](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Archiv/Update_Juli_23_R_3.2/CX-0002-DigitalTwinsInCatena-X-v.1.0.2.pdf)*(linked version 1.0.2, this KIT refers to v2.0.0, to be released in 09/23)*
-- CX - 0053 BPN Discovery Services *(v1.0.0 to be released in 09/23)*
+- [CX - 0001 EDC Discovery API](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0001-EDCDiscoveryAPI_v1.0.2.pdf) *(version 1.0.2)*
+- [CX - 0002 Digital Twins in Catena-X](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_Januar_2024/CX-0002-DigitalTwinsInCatenaX-v2.1.0.pdf)*(version 2.1.0)*
+- [CX - 0053 BPN Discovery Service](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_Januar_2024/CX-0053-BPNDiscoveryServiceAPIs-v1.0.1.pdf) *(version 1.0.1)*
 
-### Terminology 
+### Terminology
 
-The following figure is also a non-normative part of CX-0002 "Digital Twins in Catena-X" v2.0.0. When published, that 
-standard can be found in the [Catena-X standard library](https://catena-x.net/de/standard-library).
-![How words relate in the DT Kit](assets/img/DTKIT_terminology.svg)
+CX-0002 includes a figure on how the terms (also used in this Kit) interrelate. Check it out on page 5 of the [published
+standard](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_Januar_2024/CX-0002-DigitalTwinsInCatenaX-v2.1.0.pdf).
+
+## Notice
+
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation
+- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc)
diff --git a/docs-kits/kits/Digital Twin Kit/page_changelog.md b/docs-kits/kits/Digital Twin Kit/page_changelog.md
@@ -9,7 +9,11 @@ sidebar_position: 1
 
 ### Digital Twin KIT
 
-All notable changes to this Kit will be documented in this file.
+## [1.2.0] - 2024-03-02
+
+- Added more details on interaction patterns
+- Added guidance on confidentiality classification of properties
+- bugfixes, clarifications
 
 ## [1.1.0] - 2023-12-05
 
@@ -23,7 +27,6 @@ All notable changes to this Kit will be documented in this file.
 - A couple of clarifications and bugfixes for R23-12
 - Version of Kit incremented as minor revision since no breaking changes occurred.
 
-
 ## [1.0.0] - 2023-08-17
 
 ### Added
@@ -53,7 +56,6 @@ All notable changes to this Kit will be documented in this file.
 
 - ./.
 
-
 ## [0.1.0] - 2023-07-12
 
 <h3>Added</h3>
@@ -67,3 +69,11 @@ All notable changes to this Kit will be documented in this file.
 <h3>Removed</h3>
 
 - ./.
+
+## Notice
+
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation
+- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc)
diff --git a/docs-kits/kits/Digital Twin Kit/page_software-operation-view.md b/docs-kits/kits/Digital Twin Kit/page_software-operation-view.md
@@ -18,13 +18,30 @@ Digital Twins the Catena-X-way. This infrastructure empowers Data Consumers to c
 each Data Provider and facilitated by an Operating Company. They run central and decentral services that allow them to
 discover each other, exchange information and contextualize it according to a standardized semantics.
 
-| Service Name          | Description                                                                                              | Reference Implementation                                                                                                                                                                            | [Standardized in](https://catena-x.net/de/standard-library) |
-|-----------------------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
-| Discovery Finder      | A microservice resolving a type of identifiers against a set of BPN-Discovery Servers.                   | [Tractus-X Discovery Finder](https://github.com/eclipse-tractusx/sldt-discovery-finder)                                                                                                             | CX - 0053                                                   |
-| BPN Discovery         | A microservice resolving a particular assetId against the registered BPN of its owner.                   | [Tractus-X BPN Discovery](https://github.com/eclipse-tractusx/sldt-bpn-discovery)                                                                                                                   | CX - 0053                                                   |
-| EDC Discovery         | A microservice that resolves a BPN against an EDC endpoint.                                              | [Tractus-X Portal including EDC Discovoery API](https://github.com/eclipse-tractusx/portal-backend)                                                                                                 | CX - 0001                                                   |
-| Digital Twin Registry | An exhaustive list of all Submodel Servers, with link to their assets, adhering to the AAS Registry API. | [Tractus-X Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry)                                                                                                   | CX - 0002                                                   |
-| Submodel Server       | The data source adhering to a subset of the Submodel API as defined in AAS Part-2 3.0.                   | [FA³ST-Framework](https://github.com/FraunhoferIOSB/FAAAST-Service), [Eclipse Basyx](https://github.com/eclipse-basyx/basyx-java-sdk), [AASX Server](https://github.com/admin-shell-io/aasx-server) | CX - 0002                                                   |
+The APIs for digital twins are based on the specifications of the Asset Administration Shell (AAS) as defined in
+CX-0002.
 
+## Deployment
 
-![High Level Architecture of an App leveraging the Digital Twin Kit](assets/img/DTKIT_high_level_arch.svg)
+| Service Name          | Description                                                                                                                                       | Reference Implementation                                                                                                                                                                                        | [Standardized in](https://catena-x.net/de/standard-library) |
+|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------|
+| Discovery Finder      | A microservice resolving type of identifiers against a set of BPN-Discovery Servers.                                                              | [Tractus-X Discovery Finder](https://github.com/eclipse-tractusx/sldt-discovery-finder)                                                                                                                         | CX - 0053                                                   |
+| BPN Discovery         | A microservice resolving a particular assetId against the registered BPN of its owner.                                                            | [Tractus-X BPN Discovery](https://github.com/eclipse-tractusx/sldt-bpn-discovery)                                                                                                                               | CX - 0053                                                   |
+| EDC Discovery         | A microservice that resolves a BPN against an EDC endpoint.                                                                                       | [Tractus-X Portal including EDC Discovery API](https://github.com/eclipse-tractusx/portal-backend)                                                                                                              | CX - 0001                                                   |
+| Digital Twin Registry | A registry for digital twins, each digital twin providing the endpoints of its submodels. <br/> The registry is adhering to the AAS Registry API. | [Tractus-X Digital Twin Registry](https://github.com/eclipse-tractusx/sldt-digital-twin-registry)                                                                                                               | CX - 0002                                                   |
+| Submodel Server       | The data source adhering to a subset of the Submodel API as defined in AAS Part-2 3.0.                                                            | [FA³ST-Framework](https://github.com/FraunhoferIOSB/FAAAST-Service), <br/> [Eclipse Basyx](https://github.com/eclipse-basyx/basyx-java-sdk), <br/> [AASX Server](https://github.com/admin-shell-io/aasx-server) | CX - 0002                                                   |
+
+![High Level Architecture of an App leveraging the Digital Twin Kit](assets/img/DTKIT_high_level_arch.svg)
+
+## Setup Guide
+
+Detailed guidance on setup of the abovementioned components can be found in the repositories of their linked reference
+implementations.
+
+## Notice
+
+This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+- SPDX-License-Identifier: CC-BY-4.0
+- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation
+- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc)
diff --git a/docs-kits_versioned_sidebars/version-3.1.0-sidebars.json b/docs-kits_versioned_sidebars/version-3.1.0-sidebars.json
@@ -817,20 +817,6 @@
         }
       ]
     },
-    {
-      "type": "category",
-      "label": "Digital Twin Kit",
-      "link": {
-        "type": "generated-index"
-      },
-      "collapsed": true,
-      "items": [
-        {
-          "type": "autogenerated",
-          "dirName": "kits/Digital Twin Kit"
-        }
-      ]
-    },
     {
       "type": "category",
       "label": "Traceability KIT",

diff --git a/openApi/dt/discovery-finder-openapi.yaml b/openApi/dt/discovery-finder-openapi.yaml
@@ -132,6 +132,7 @@ components:
         - type
         - description
         - endpointAddress
+        - timeToLive
       properties:
         type:
           type: string
@@ -151,6 +152,10 @@ components:
           maxLength: 500
         resourceId:
           type: string
+        timeToLive:
+          type: integer
+          minimum: 1
+          maximum: 31536000
     SearchRequest:
       title: SearchRequest
       required:
@@ -209,7 +214,8 @@ components:
           "type": "oen",
           "description": "Service to discover BPN to a particular OEN",
           "endpointAddress": "http://...",
-          "documentation": "http://.../swagger/index.html"
+          "documentation": "http://.../swagger/index.html",
+          "timeToLive": 31536000
         }
     discovery-endpoint-result:
       value:
@@ -218,7 +224,8 @@ components:
           "description": "Service to discover BPN to a particular OEN",
           "endpointAddress": "http://...",
           "documentation": "http://.../swagger/index.html",
-          "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67"
+          "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67",
+          "timeToLive": 31536000
         }
     discovey-endpoint-search:
       value:
@@ -234,21 +241,24 @@ components:
               "description": "Service to discover BPN to a particular OEN",
               "endpointAddress": "http://...",
               "documentation": "http://.../swagger/index.html",
-              "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67"
+              "resourceId": "ec6f407b-4296-418c-9e4e-fb739fe72a67",
+              "timeToLive": 31536000
             },
             {
               "type": "bpid",
               "description": "Service to discover BPN to a particular Battery Pass ID",
               "endpointAddress": "http://...",
               "documentation": "http://.../swagger/index.html",
-              "resourceId": "08702529-3714-4c4f-b022-346b9b4fbbe2"
+              "resourceId": "08702529-3714-4c4f-b022-346b9b4fbbe2",
+              "timeToLive": 31536000
             },
             {
               "type": "bpn",
               "description": "Service to discover EDC to a particular BPN",
               "endpointAddress": "http://...",
               "documentation": "http://.../swagger/index.html",
-              "resourceId": "316417cd-0fb5-4daf-8dfa-8f68125923f1"
+              "resourceId": "316417cd-0fb5-4daf-8dfa-8f68125923f1",
+              "timeToLive": 31536000
             }
           ]
         }