diff --git a/docs-kits/kits/Digital Twin Kit/Software Development View/page_software-development-view.md b/docs-kits/kits/Digital Twin Kit/Software Development View/page_software-development-view.md index ef7e2c2a883..62fae2cda79 100644 --- a/docs-kits/kits/Digital Twin Kit/Software Development View/page_software-development-view.md +++ b/docs-kits/kits/Digital Twin Kit/Software Development View/page_software-development-view.md @@ -423,13 +423,25 @@ these are the layers of complexity: | AAS Specification | 4, 5, 15, 25 | For all AAS-related EDC-Assets (styled as dcat:Dataset in the catalog), a property cx-common:version must be added referring to the major and minor version of the AAS-spec. | Unclear, under discussion in DT Kit. | | Data Model Version | 5, 21, 29 | The structure of the Submodel is determined by the aspect-model's URN. It includes a section on versioning. | A new version of the schema requires setup of a new submodel. This includes registration at the DTR. | -### Patterns for Submodels +Here's a list of duties for Data Providers in case they integrate a new Submodel (or version of an existing one) to an existing +twin: + +- Expose a new Submodel to the Dataspace. If its URL is a subpath of one that's already registered as a EDC-Asset, +there is no need to specifically register it as a new EDC-Asset and create a Contract Definition for it. However, +if there is no such EDC-Asset, that's what a Data Provider must do: create an Asset, connect it to policies via the contract- +definition-API and let consumers negotiate for it. +- If only assetIds are known, the aasId can be discovered via `GET https://mydtr.com/api/v3.0/lookup/shells?assetIds=...` as specified +by CX-0002. +- `POST https://mydtr.com/api/v3.0/shell-descriptors/{{aasId}}/submodel-descriptors` with the (known or obtained) aasId in the path +and the new submodel-descriptor in the body of the request. The attribute `semanticId` is mandatory for submodel-descriptors in Catena-X. +As defined in CX-0002, semanticIds in Catena-X are aspect-model-urns (see CX-0003) including a version. + +### Patterns for Submodel Deployment Data Providers will usually follow one of two patterns: 1. Digital Twin Repository: Deploying a dedicated Repository for the persistence of digital twins and related data is the most convenient way to get started with the AAS. Due to the risk of data duplication and unclear initial ingestion - mechanisms, -it may not scale to industrial sizes. + mechanisms, it may not scale to industrial sizes. 2. Delegation: Wrapping another API or a database may deploy the Submodel API as a new facade. It delegates the incoming requests to the respective backend systems. This is particularly feasible in the Catena-X dataspace since it @@ -444,4 +456,4 @@ see [reference implementation](https://github.com/eclipse-tractusx/sldt-digital- These APIs should only be accessible by the Data Provider (for instance by introduction of proper access control scopes or setting `proxyMethod = false`, see [registration](#digital-twin-registry-as-edc-data-asset)). Delegation as backend integration pattern is more inconvenient as the DTR must process and return reproducable IDs not only for -the assets but also for the AAS - this is hard to realize in a pure stateless implementation. \ No newline at end of file +the assets but also for the AAS - this is hard to realize in a pure stateless implementation. 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 index f8915da95de..2d2b3e07e63 100644 --- 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 @@ -1 +1 @@ -Data ConsumerSubmodel ServerDigital Twin RegistryConsumer EDC Control PlaneProvider EDC Control PlaneEDC DiscoveryBPN Discovery ServiceDiscovery FinderProvider Setup AdminData ConsumerSubmodel ServerDigital Twin RegistryConsumer EDC Control PlaneProvider EDC Control PlaneEDC DiscoveryBPN Discovery ServiceDiscovery FinderProvider Setup Admincritical[: setup of registration]loop[forEach BPN Discovery instance]critical[: discovery from data consumer side]POST /api/administration/connectors with Link between BPN and EDC endpoint1POST /api/administration/connectors/discovery with IdType-to-BPN-Discover-URL-Mapping2POST /api/administration/connectors/bpnDiscovery with assetId, idType ("van", "cxId" etcetc)3POST /api/management/v2/assets with baseUrl and typization for AAS Registry4POST /shell-descriptors for all shell descriptors of a data provider5POST /api/administration/connectors/discovery/search with body containing relevant idTypes6bpn-discovery-endpoints7POST /api/administration/connectors/bpnDiscovery/search with body containing assetId8provider-bpn9POST /api/administration/connectors/discovery with provider-bpn10EDC-endpoint11POST /catalog/request with filter looking for DTR12forward13return14dcat: Dataset for DTR15negotiate for DTR and retrieve token16access token17GET /lookup/shells?assetIds=xyz18aas-id19GET /shell-descriptors/{{aas-id}} with aas-id encoded base64url20shell-descriptor including the submodel's Dataset-ID (subprotocolBody)21POST /catalog/request with filter looking for Dataset-ID22forward23return24Dataset for submodel(-bundle)25negotiate for Dataset and retrieve token26access token27GET {{submodel-descriptor/href}}/$value28data29 \ No newline at end of file +Data ConsumerSubmodel ServerDigital Twin RegistryConsumer EDC Control PlaneProvider EDC Control PlaneEDC DiscoveryBPN Discovery ServiceDiscovery FinderProvider Setup AdminData ConsumerSubmodel ServerDigital Twin RegistryConsumer EDC Control PlaneProvider EDC Control PlaneEDC DiscoveryBPN Discovery ServiceDiscovery FinderProvider Setup Admincritical[: setup of registration]loop[forEach BPN Discovery instance]critical[: discovery from data consumer side]POST /api/administration/connectors with Link between BPN and EDC endpoint1POST /api/administration/connectors/discovery with IdType-to-BPN-Discover-URL-Mapping2POST /api/administration/connectors/bpnDiscovery with assetId, idType ("van", "cxId" etcetc)3POST /api/management/v2/assets with baseUrl and typization for AAS Registry4POST /shell-descriptors for all shell descriptors of a data provider5POST /api/administration/connectors/discovery/search with body containing relevant idTypes6bpn-discovery-endpoints7POST /api/administration/connectors/bpnDiscovery/search with body containing assetId8provider-bpn9POST /api/administration/connectors/discovery with provider-bpn10EDC-endpoint11POST /catalog/request with filter looking for DTR12forward13return14dcat: Dataset for DTR15negotiate for DTR and retrieve token16access token17GET /lookup/shells?assetIds=xyz18aas-id19GET /shell-descriptors/{{aas-id}} with aas-id encoded base64url20shell-descriptor including the submodel's Dataset-ID (subprotocolBody)21POST /catalog/request with filter looking for Dataset-ID22forward23return24Dataset for submodel(-bundle)25negotiate for Dataset and retrieve token26access token27GET {{submodel-descriptor/href}}/$value28data29 \ No newline at end of file diff --git a/docs-kits/kits/Digital Twin Kit/page_changelog.md b/docs-kits/kits/Digital Twin Kit/page_changelog.md index fabd05e81c0..3b44dba4a17 100644 --- a/docs-kits/kits/Digital Twin Kit/page_changelog.md +++ b/docs-kits/kits/Digital Twin Kit/page_changelog.md @@ -11,6 +11,19 @@ sidebar_position: 1 All notable changes to this Kit will be documented in this file. +## [1.1.0] - 2023-12-05 + +### Added + +- remarks on versioning +- guidance for adding submodels to existing twins + +### Changed + +- 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